Create firm

Creates a firm for the current authenticated client and registers an existing user as a staff member and firm owner.

POST /firm

Create firm

cURL

curl --request POST \
  --url https://api.smokeball.com/firm \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json-patch+json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "productId": "SMK001",
  "addOnIds": [
    "ADD01",
    "ADD003"
  ],
  "name": "Brown LLC",
  "email": "[e-mail]",
  "abn": "1234567890",
  "acn": "1234567890",
  "streetAddress": {
    "buildingLevel": "Level 1",
    "unitNumber": "10",
    "unitType": "Suite",
    "streetNumber": "100",
    "streetName": "Broad",
    "streetType": "Street",
    "addressLine1": "Level 1/10",
    "addressLine2": "100 Broad Street",
    "city": "Chicago",
    "state": "IL",
    "zipCode": "60606",
    "county": "",
    "locality": "",
    "country": "United States",
    "careOf": "",
    "poBoxType": "",
    "poBoxNumber": ""
  },
  "mailingAddress": {
    "buildingLevel": "Level 1",
    "unitNumber": "10",
    "unitType": "Suite",
    "streetNumber": "100",
    "streetName": "Broad",
    "streetType": "Street",
    "addressLine1": "Level 1/10",
    "addressLine2": "100 Broad Street",
    "city": "Chicago",
    "state": "IL",
    "zipCode": "60606",
    "county": "",
    "locality": "",
    "country": "United States",
    "careOf": "",
    "poBoxType": "",
    "poBoxNumber": ""
  },
  "dxAddress": {
    "number": "376",
    "exchange": "DX",
    "state": "NSW"
  },
  "phone": {
    "areaCode": "555",
    "number": "1234567"
  },
  "fax": {
    "areaCode": "555",
    "number": "1234567"
  },
  "isInternal": false,
  "staff": {
    "userId": "b471682e-fa17-4e46-b7fe-9b2b8fdcb3c2",
    "title": "Mr",
    "firstName": "John",
    "middleName": "",
    "lastName": "Smith",
    "initials": "JS",
    "phone": {
      "areaCode": "555",
      "number": "1234567"
    },
    "cell": {
      "areaCode": "555",
      "number": "1234567"
    },
    "email": "[e-mail]",
    "role": "Bookkeeper",
    "avatar": "https://example-avatar-url.com/image",
    "former": false,
    "colorFill": "#797d85",
    "colorStroke": "#64666a"
  },
  "subscription": {
    "productSuite": "<string>",
    "promotionId": "<string>",
    "interval": "<string>"
  }
}
'

import requests

url = "https://api.smokeball.com/firm"

payload = {
    "productId": "SMK001",
    "addOnIds": ["ADD01", "ADD003"],
    "name": "Brown LLC",
    "email": "[e-mail]",
    "abn": "1234567890",
    "acn": "1234567890",
    "streetAddress": {
        "buildingLevel": "Level 1",
        "unitNumber": "10",
        "unitType": "Suite",
        "streetNumber": "100",
        "streetName": "Broad",
        "streetType": "Street",
        "addressLine1": "Level 1/10",
        "addressLine2": "100 Broad Street",
        "city": "Chicago",
        "state": "IL",
        "zipCode": "60606",
        "county": "",
        "locality": "",
        "country": "United States",
        "careOf": "",
        "poBoxType": "",
        "poBoxNumber": ""
    },
    "mailingAddress": {
        "buildingLevel": "Level 1",
        "unitNumber": "10",
        "unitType": "Suite",
        "streetNumber": "100",
        "streetName": "Broad",
        "streetType": "Street",
        "addressLine1": "Level 1/10",
        "addressLine2": "100 Broad Street",
        "city": "Chicago",
        "state": "IL",
        "zipCode": "60606",
        "county": "",
        "locality": "",
        "country": "United States",
        "careOf": "",
        "poBoxType": "",
        "poBoxNumber": ""
    },
    "dxAddress": {
        "number": "376",
        "exchange": "DX",
        "state": "NSW"
    },
    "phone": {
        "areaCode": "555",
        "number": "1234567"
    },
    "fax": {
        "areaCode": "555",
        "number": "1234567"
    },
    "isInternal": False,
    "staff": {
        "userId": "b471682e-fa17-4e46-b7fe-9b2b8fdcb3c2",
        "title": "Mr",
        "firstName": "John",
        "middleName": "",
        "lastName": "Smith",
        "initials": "JS",
        "phone": {
            "areaCode": "555",
            "number": "1234567"
        },
        "cell": {
            "areaCode": "555",
            "number": "1234567"
        },
        "email": "[e-mail]",
        "role": "Bookkeeper",
        "avatar": "https://example-avatar-url.com/image",
        "former": False,
        "colorFill": "#797d85",
        "colorStroke": "#64666a"
    },
    "subscription": {
        "productSuite": "<string>",
        "promotionId": "<string>",
        "interval": "<string>"
    }
}
headers = {
    "x-api-key": "<api-key>",
    "Authorization": "<api-key>",
    "Content-Type": "application/json-patch+json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'x-api-key': '<api-key>',
    Authorization: '<api-key>',
    'Content-Type': 'application/json-patch+json'
  },
  body: JSON.stringify({
    productId: 'SMK001',
    addOnIds: ['ADD01', 'ADD003'],
    name: 'Brown LLC',
    email: '[e-mail]',
    abn: '1234567890',
    acn: '1234567890',
    streetAddress: {
      buildingLevel: 'Level 1',
      unitNumber: '10',
      unitType: 'Suite',
      streetNumber: '100',
      streetName: 'Broad',
      streetType: 'Street',
      addressLine1: 'Level 1/10',
      addressLine2: '100 Broad Street',
      city: 'Chicago',
      state: 'IL',
      zipCode: '60606',
      county: '',
      locality: '',
      country: 'United States',
      careOf: '',
      poBoxType: '',
      poBoxNumber: ''
    },
    mailingAddress: {
      buildingLevel: 'Level 1',
      unitNumber: '10',
      unitType: 'Suite',
      streetNumber: '100',
      streetName: 'Broad',
      streetType: 'Street',
      addressLine1: 'Level 1/10',
      addressLine2: '100 Broad Street',
      city: 'Chicago',
      state: 'IL',
      zipCode: '60606',
      county: '',
      locality: '',
      country: 'United States',
      careOf: '',
      poBoxType: '',
      poBoxNumber: ''
    },
    dxAddress: {number: '376', exchange: 'DX', state: 'NSW'},
    phone: {areaCode: '555', number: '1234567'},
    fax: {areaCode: '555', number: '1234567'},
    isInternal: false,
    staff: {
      userId: 'b471682e-fa17-4e46-b7fe-9b2b8fdcb3c2',
      title: 'Mr',
      firstName: 'John',
      middleName: '',
      lastName: 'Smith',
      initials: 'JS',
      phone: {areaCode: '555', number: '1234567'},
      cell: {areaCode: '555', number: '1234567'},
      email: '[e-mail]',
      role: 'Bookkeeper',
      avatar: 'https://example-avatar-url.com/image',
      former: false,
      colorFill: '#797d85',
      colorStroke: '#64666a'
    },
    subscription: {productSuite: '<string>', promotionId: '<string>', interval: '<string>'}
  })
};

fetch('https://api.smokeball.com/firm', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.smokeball.com/firm",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'productId' => 'SMK001',
    'addOnIds' => [
        'ADD01',
        'ADD003'
    ],
    'name' => 'Brown LLC',
    'email' => '[e-mail]',
    'abn' => '1234567890',
    'acn' => '1234567890',
    'streetAddress' => [
        'buildingLevel' => 'Level 1',
        'unitNumber' => '10',
        'unitType' => 'Suite',
        'streetNumber' => '100',
        'streetName' => 'Broad',
        'streetType' => 'Street',
        'addressLine1' => 'Level 1/10',
        'addressLine2' => '100 Broad Street',
        'city' => 'Chicago',
        'state' => 'IL',
        'zipCode' => '60606',
        'county' => '',
        'locality' => '',
        'country' => 'United States',
        'careOf' => '',
        'poBoxType' => '',
        'poBoxNumber' => ''
    ],
    'mailingAddress' => [
        'buildingLevel' => 'Level 1',
        'unitNumber' => '10',
        'unitType' => 'Suite',
        'streetNumber' => '100',
        'streetName' => 'Broad',
        'streetType' => 'Street',
        'addressLine1' => 'Level 1/10',
        'addressLine2' => '100 Broad Street',
        'city' => 'Chicago',
        'state' => 'IL',
        'zipCode' => '60606',
        'county' => '',
        'locality' => '',
        'country' => 'United States',
        'careOf' => '',
        'poBoxType' => '',
        'poBoxNumber' => ''
    ],
    'dxAddress' => [
        'number' => '376',
        'exchange' => 'DX',
        'state' => 'NSW'
    ],
    'phone' => [
        'areaCode' => '555',
        'number' => '1234567'
    ],
    'fax' => [
        'areaCode' => '555',
        'number' => '1234567'
    ],
    'isInternal' => false,
    'staff' => [
        'userId' => 'b471682e-fa17-4e46-b7fe-9b2b8fdcb3c2',
        'title' => 'Mr',
        'firstName' => 'John',
        'middleName' => '',
        'lastName' => 'Smith',
        'initials' => 'JS',
        'phone' => [
                'areaCode' => '555',
                'number' => '1234567'
        ],
        'cell' => [
                'areaCode' => '555',
                'number' => '1234567'
        ],
        'email' => '[e-mail]',
        'role' => 'Bookkeeper',
        'avatar' => 'https://example-avatar-url.com/image',
        'former' => false,
        'colorFill' => '#797d85',
        'colorStroke' => '#64666a'
    ],
    'subscription' => [
        'productSuite' => '<string>',
        'promotionId' => '<string>',
        'interval' => '<string>'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "Content-Type: application/json-patch+json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.smokeball.com/firm"

	payload := strings.NewReader("{\n  \"productId\": \"SMK001\",\n  \"addOnIds\": [\n    \"ADD01\",\n    \"ADD003\"\n  ],\n  \"name\": \"Brown LLC\",\n  \"email\": \"[e-mail]\",\n  \"abn\": \"1234567890\",\n  \"acn\": \"1234567890\",\n  \"streetAddress\": {\n    \"buildingLevel\": \"Level 1\",\n    \"unitNumber\": \"10\",\n    \"unitType\": \"Suite\",\n    \"streetNumber\": \"100\",\n    \"streetName\": \"Broad\",\n    \"streetType\": \"Street\",\n    \"addressLine1\": \"Level 1/10\",\n    \"addressLine2\": \"100 Broad Street\",\n    \"city\": \"Chicago\",\n    \"state\": \"IL\",\n    \"zipCode\": \"60606\",\n    \"county\": \"\",\n    \"locality\": \"\",\n    \"country\": \"United States\",\n    \"careOf\": \"\",\n    \"poBoxType\": \"\",\n    \"poBoxNumber\": \"\"\n  },\n  \"mailingAddress\": {\n    \"buildingLevel\": \"Level 1\",\n    \"unitNumber\": \"10\",\n    \"unitType\": \"Suite\",\n    \"streetNumber\": \"100\",\n    \"streetName\": \"Broad\",\n    \"streetType\": \"Street\",\n    \"addressLine1\": \"Level 1/10\",\n    \"addressLine2\": \"100 Broad Street\",\n    \"city\": \"Chicago\",\n    \"state\": \"IL\",\n    \"zipCode\": \"60606\",\n    \"county\": \"\",\n    \"locality\": \"\",\n    \"country\": \"United States\",\n    \"careOf\": \"\",\n    \"poBoxType\": \"\",\n    \"poBoxNumber\": \"\"\n  },\n  \"dxAddress\": {\n    \"number\": \"376\",\n    \"exchange\": \"DX\",\n    \"state\": \"NSW\"\n  },\n  \"phone\": {\n    \"areaCode\": \"555\",\n    \"number\": \"1234567\"\n  },\n  \"fax\": {\n    \"areaCode\": \"555\",\n    \"number\": \"1234567\"\n  },\n  \"isInternal\": false,\n  \"staff\": {\n    \"userId\": \"b471682e-fa17-4e46-b7fe-9b2b8fdcb3c2\",\n    \"title\": \"Mr\",\n    \"firstName\": \"John\",\n    \"middleName\": \"\",\n    \"lastName\": \"Smith\",\n    \"initials\": \"JS\",\n    \"phone\": {\n      \"areaCode\": \"555\",\n      \"number\": \"1234567\"\n    },\n    \"cell\": {\n      \"areaCode\": \"555\",\n      \"number\": \"1234567\"\n    },\n    \"email\": \"[e-mail]\",\n    \"role\": \"Bookkeeper\",\n    \"avatar\": \"https://example-avatar-url.com/image\",\n    \"former\": false,\n    \"colorFill\": \"#797d85\",\n    \"colorStroke\": \"#64666a\"\n  },\n  \"subscription\": {\n    \"productSuite\": \"<string>\",\n    \"promotionId\": \"<string>\",\n    \"interval\": \"<string>\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Authorization", "<api-key>")
	req.Header.Add("Content-Type", "application/json-patch+json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.smokeball.com/firm")
  .header("x-api-key", "<api-key>")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/json-patch+json")
  .body("{\n  \"productId\": \"SMK001\",\n  \"addOnIds\": [\n    \"ADD01\",\n    \"ADD003\"\n  ],\n  \"name\": \"Brown LLC\",\n  \"email\": \"[e-mail]\",\n  \"abn\": \"1234567890\",\n  \"acn\": \"1234567890\",\n  \"streetAddress\": {\n    \"buildingLevel\": \"Level 1\",\n    \"unitNumber\": \"10\",\n    \"unitType\": \"Suite\",\n    \"streetNumber\": \"100\",\n    \"streetName\": \"Broad\",\n    \"streetType\": \"Street\",\n    \"addressLine1\": \"Level 1/10\",\n    \"addressLine2\": \"100 Broad Street\",\n    \"city\": \"Chicago\",\n    \"state\": \"IL\",\n    \"zipCode\": \"60606\",\n    \"county\": \"\",\n    \"locality\": \"\",\n    \"country\": \"United States\",\n    \"careOf\": \"\",\n    \"poBoxType\": \"\",\n    \"poBoxNumber\": \"\"\n  },\n  \"mailingAddress\": {\n    \"buildingLevel\": \"Level 1\",\n    \"unitNumber\": \"10\",\n    \"unitType\": \"Suite\",\n    \"streetNumber\": \"100\",\n    \"streetName\": \"Broad\",\n    \"streetType\": \"Street\",\n    \"addressLine1\": \"Level 1/10\",\n    \"addressLine2\": \"100 Broad Street\",\n    \"city\": \"Chicago\",\n    \"state\": \"IL\",\n    \"zipCode\": \"60606\",\n    \"county\": \"\",\n    \"locality\": \"\",\n    \"country\": \"United States\",\n    \"careOf\": \"\",\n    \"poBoxType\": \"\",\n    \"poBoxNumber\": \"\"\n  },\n  \"dxAddress\": {\n    \"number\": \"376\",\n    \"exchange\": \"DX\",\n    \"state\": \"NSW\"\n  },\n  \"phone\": {\n    \"areaCode\": \"555\",\n    \"number\": \"1234567\"\n  },\n  \"fax\": {\n    \"areaCode\": \"555\",\n    \"number\": \"1234567\"\n  },\n  \"isInternal\": false,\n  \"staff\": {\n    \"userId\": \"b471682e-fa17-4e46-b7fe-9b2b8fdcb3c2\",\n    \"title\": \"Mr\",\n    \"firstName\": \"John\",\n    \"middleName\": \"\",\n    \"lastName\": \"Smith\",\n    \"initials\": \"JS\",\n    \"phone\": {\n      \"areaCode\": \"555\",\n      \"number\": \"1234567\"\n    },\n    \"cell\": {\n      \"areaCode\": \"555\",\n      \"number\": \"1234567\"\n    },\n    \"email\": \"[e-mail]\",\n    \"role\": \"Bookkeeper\",\n    \"avatar\": \"https://example-avatar-url.com/image\",\n    \"former\": false,\n    \"colorFill\": \"#797d85\",\n    \"colorStroke\": \"#64666a\"\n  },\n  \"subscription\": {\n    \"productSuite\": \"<string>\",\n    \"promotionId\": \"<string>\",\n    \"interval\": \"<string>\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.smokeball.com/firm")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json-patch+json'
request.body = "{\n  \"productId\": \"SMK001\",\n  \"addOnIds\": [\n    \"ADD01\",\n    \"ADD003\"\n  ],\n  \"name\": \"Brown LLC\",\n  \"email\": \"[e-mail]\",\n  \"abn\": \"1234567890\",\n  \"acn\": \"1234567890\",\n  \"streetAddress\": {\n    \"buildingLevel\": \"Level 1\",\n    \"unitNumber\": \"10\",\n    \"unitType\": \"Suite\",\n    \"streetNumber\": \"100\",\n    \"streetName\": \"Broad\",\n    \"streetType\": \"Street\",\n    \"addressLine1\": \"Level 1/10\",\n    \"addressLine2\": \"100 Broad Street\",\n    \"city\": \"Chicago\",\n    \"state\": \"IL\",\n    \"zipCode\": \"60606\",\n    \"county\": \"\",\n    \"locality\": \"\",\n    \"country\": \"United States\",\n    \"careOf\": \"\",\n    \"poBoxType\": \"\",\n    \"poBoxNumber\": \"\"\n  },\n  \"mailingAddress\": {\n    \"buildingLevel\": \"Level 1\",\n    \"unitNumber\": \"10\",\n    \"unitType\": \"Suite\",\n    \"streetNumber\": \"100\",\n    \"streetName\": \"Broad\",\n    \"streetType\": \"Street\",\n    \"addressLine1\": \"Level 1/10\",\n    \"addressLine2\": \"100 Broad Street\",\n    \"city\": \"Chicago\",\n    \"state\": \"IL\",\n    \"zipCode\": \"60606\",\n    \"county\": \"\",\n    \"locality\": \"\",\n    \"country\": \"United States\",\n    \"careOf\": \"\",\n    \"poBoxType\": \"\",\n    \"poBoxNumber\": \"\"\n  },\n  \"dxAddress\": {\n    \"number\": \"376\",\n    \"exchange\": \"DX\",\n    \"state\": \"NSW\"\n  },\n  \"phone\": {\n    \"areaCode\": \"555\",\n    \"number\": \"1234567\"\n  },\n  \"fax\": {\n    \"areaCode\": \"555\",\n    \"number\": \"1234567\"\n  },\n  \"isInternal\": false,\n  \"staff\": {\n    \"userId\": \"b471682e-fa17-4e46-b7fe-9b2b8fdcb3c2\",\n    \"title\": \"Mr\",\n    \"firstName\": \"John\",\n    \"middleName\": \"\",\n    \"lastName\": \"Smith\",\n    \"initials\": \"JS\",\n    \"phone\": {\n      \"areaCode\": \"555\",\n      \"number\": \"1234567\"\n    },\n    \"cell\": {\n      \"areaCode\": \"555\",\n      \"number\": \"1234567\"\n    },\n    \"email\": \"[e-mail]\",\n    \"role\": \"Bookkeeper\",\n    \"avatar\": \"https://example-avatar-url.com/image\",\n    \"former\": false,\n    \"colorFill\": \"#797d85\",\n    \"colorStroke\": \"#64666a\"\n  },\n  \"subscription\": {\n    \"productSuite\": \"<string>\",\n    \"promotionId\": \"<string>\",\n    \"interval\": \"<string>\"\n  }\n}"

response = http.request(request)
puts response.read_body

202

{
  "id": "<string>",
  "href": "<string>",
  "relation": "<string>",
  "method": "GET"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "instance": "<string>"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "instance": "<string>"
}

Authorizations

x-api-key · string · header · required

Authorization · string · header · required

Body

application/json-patch+jsonapplication/jsonapplication/*+json

productId · string | null

The product/tier the firm is subscribed to. Must be set when creating the firm and is optional when updating the firm.

The supported products are listed in order below, the identifier (in brackets) must be used.

• Bill (SMK001)

• Boost (SMK004)

• Grow (SMK002)

• Prosper + (SMK003)

Possible values: SMK001, SMK004, SMK002, SMK003

Example:

"SMK001"

addOnIds · string[] | null

The optional add-ons the firm is subscribed to. Must be specified with an accompanying productId.

The supported add-ons are listed below, the identifier (listed in brackets) must be used.

• Intake (ADD001)

• AutoTime (ADD003)

• FamilyPro (ADD004)

• Api (ADD005)

• Workflows (ADD006)

• PowerBI (ADD007)

• Archie (ADD008)

• SSO (ADD010)

Possible values: ADD01, ADD003, ADD004, ADD005, ADD006, ADD007, ADD008, ADD010

Example:

["ADD01", "ADD003"]

name · string | null

The name of the firm.

Example:

"Brown LLC"

email · string | null

The email of the firm.

Only supported in AU.

Example:

"[e-mail]"

abn · string | null

Represents a different field depending on the region.

• For AU: Australian Business Number (ABN) of the firm.

• For UK: Value-added Tax Number (VAT) of the firm.

Only supported in AU and UK.

Example:

"1234567890"

acn · string | null

Represents a different field depending on the region.

• For AU: Australian Company Number (ACN) of the firm.

• For UK: Company Registration Number (CRN) of the firm.

Only supported in AU and UK.

Example:

"1234567890"

streetAddress · object | null

Street address of the firm.

Show child attributes

mailingAddress · object | null

Mailing address of the firm.

Show child attributes

dxAddress · object | null

DX address of the firm.

Only supported in AU.

Show child attributes

phone · object | null

Phone number of the firm.

Show child attributes

fax · object | null

Fax number of the firm.

Show child attributes

isInternal · boolean

Whether firm is being created for internal use. Internal firms will not be subscribed for payment processing and will not be charged.

Example:

false

staff · object | null

The staff member that will be created with the firm. This staff member will become the firm owner.

Show child attributes

subscription · object | null

Optional subscription details that will be used when creating the firm.

Show child attributes

Response

202

application/json

When request is accepted. Returns a hypermedia 'Link' object of the firm to be created.

id · string | null

href · string | null

relation · string | null

method · string | null · default: GET