Skip to main content
POST
/
v0
/
instance
Create an Instance
curl --request POST \
  --url https://api.sandbox.teal.dev/v0/instance \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "entries_start": "2023-11-07T05:31:56Z",
  "name": "<string>",
  "coa_template_id": "CNmWM3X6AcvRdEwZKxq4bL",
  "custom_coa": {
    "ledgers": [
      {
        "name": "<string>",
        "sort_code": "<string>",
        "children": [
          "<unknown>"
        ]
      }
    ],
    "required_ledgers": {
      "uncategorized_inflow": {
        "name": "Uncategorized Cash Inflow",
        "sort_code": "0"
      },
      "uncategorized_outflow": {
        "name": "Uncategorized Cash Outflow",
        "sort_code": "1"
      },
      "transfers_between_accounts": {
        "name": "Transfers Between Accounts",
        "sort_code": "2"
      },
      "opening_balances": {
        "name": "Opening Balance Retained Earnings",
        "sort_code": "3"
      },
      "accounts_receivable": {
        "name": "Accounts Receivable",
        "sort_code": "4"
      },
      "accounts_payable": {
        "name": "Accounts Payable",
        "sort_code": "6"
      },
      "retained_earnings": {
        "name": "Retained Earnings",
        "sort_code": "8020"
      },
      "current_year_earnings": {
        "name": "Current Year Earnings",
        "sort_code": "8030"
      }
    }
  },
  "subscription": "tier0",
  "accounting_basis": "accrual"
}
'
import requests

url = "https://api.sandbox.teal.dev/v0/instance"

payload = {
    "entries_start": "2023-11-07T05:31:56Z",
    "name": "<string>",
    "coa_template_id": "CNmWM3X6AcvRdEwZKxq4bL",
    "custom_coa": {
        "ledgers": [
            {
                "name": "<string>",
                "sort_code": "<string>",
                "children": ["<unknown>"]
            }
        ],
        "required_ledgers": {
            "uncategorized_inflow": {
                "name": "Uncategorized Cash Inflow",
                "sort_code": "0"
            },
            "uncategorized_outflow": {
                "name": "Uncategorized Cash Outflow",
                "sort_code": "1"
            },
            "transfers_between_accounts": {
                "name": "Transfers Between Accounts",
                "sort_code": "2"
            },
            "opening_balances": {
                "name": "Opening Balance Retained Earnings",
                "sort_code": "3"
            },
            "accounts_receivable": {
                "name": "Accounts Receivable",
                "sort_code": "4"
            },
            "accounts_payable": {
                "name": "Accounts Payable",
                "sort_code": "6"
            },
            "retained_earnings": {
                "name": "Retained Earnings",
                "sort_code": "8020"
            },
            "current_year_earnings": {
                "name": "Current Year Earnings",
                "sort_code": "8030"
            }
        }
    },
    "subscription": "tier0",
    "accounting_basis": "accrual"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    entries_start: '2023-11-07T05:31:56Z',
    name: '<string>',
    coa_template_id: 'CNmWM3X6AcvRdEwZKxq4bL',
    custom_coa: {
      ledgers: [{name: '<string>', sort_code: '<string>', children: ['<unknown>']}],
      required_ledgers: {
        uncategorized_inflow: {name: 'Uncategorized Cash Inflow', sort_code: '0'},
        uncategorized_outflow: {name: 'Uncategorized Cash Outflow', sort_code: '1'},
        transfers_between_accounts: {name: 'Transfers Between Accounts', sort_code: '2'},
        opening_balances: {name: 'Opening Balance Retained Earnings', sort_code: '3'},
        accounts_receivable: {name: 'Accounts Receivable', sort_code: '4'},
        accounts_payable: {name: 'Accounts Payable', sort_code: '6'},
        retained_earnings: {name: 'Retained Earnings', sort_code: '8020'},
        current_year_earnings: {name: 'Current Year Earnings', sort_code: '8030'}
      }
    },
    subscription: 'tier0',
    accounting_basis: 'accrual'
  })
};

fetch('https://api.sandbox.teal.dev/v0/instance', 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.sandbox.teal.dev/v0/instance",
  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([
    'entries_start' => '2023-11-07T05:31:56Z',
    'name' => '<string>',
    'coa_template_id' => 'CNmWM3X6AcvRdEwZKxq4bL',
    'custom_coa' => [
        'ledgers' => [
                [
                                'name' => '<string>',
                                'sort_code' => '<string>',
                                'children' => [
                                                                '<unknown>'
                                ]
                ]
        ],
        'required_ledgers' => [
                'uncategorized_inflow' => [
                                'name' => 'Uncategorized Cash Inflow',
                                'sort_code' => '0'
                ],
                'uncategorized_outflow' => [
                                'name' => 'Uncategorized Cash Outflow',
                                'sort_code' => '1'
                ],
                'transfers_between_accounts' => [
                                'name' => 'Transfers Between Accounts',
                                'sort_code' => '2'
                ],
                'opening_balances' => [
                                'name' => 'Opening Balance Retained Earnings',
                                'sort_code' => '3'
                ],
                'accounts_receivable' => [
                                'name' => 'Accounts Receivable',
                                'sort_code' => '4'
                ],
                'accounts_payable' => [
                                'name' => 'Accounts Payable',
                                'sort_code' => '6'
                ],
                'retained_earnings' => [
                                'name' => 'Retained Earnings',
                                'sort_code' => '8020'
                ],
                'current_year_earnings' => [
                                'name' => 'Current Year Earnings',
                                'sort_code' => '8030'
                ]
        ]
    ],
    'subscription' => 'tier0',
    'accounting_basis' => 'accrual'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$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.sandbox.teal.dev/v0/instance"

	payload := strings.NewReader("{\n  \"entries_start\": \"2023-11-07T05:31:56Z\",\n  \"name\": \"<string>\",\n  \"coa_template_id\": \"CNmWM3X6AcvRdEwZKxq4bL\",\n  \"custom_coa\": {\n    \"ledgers\": [\n      {\n        \"name\": \"<string>\",\n        \"sort_code\": \"<string>\",\n        \"children\": [\n          \"<unknown>\"\n        ]\n      }\n    ],\n    \"required_ledgers\": {\n      \"uncategorized_inflow\": {\n        \"name\": \"Uncategorized Cash Inflow\",\n        \"sort_code\": \"0\"\n      },\n      \"uncategorized_outflow\": {\n        \"name\": \"Uncategorized Cash Outflow\",\n        \"sort_code\": \"1\"\n      },\n      \"transfers_between_accounts\": {\n        \"name\": \"Transfers Between Accounts\",\n        \"sort_code\": \"2\"\n      },\n      \"opening_balances\": {\n        \"name\": \"Opening Balance Retained Earnings\",\n        \"sort_code\": \"3\"\n      },\n      \"accounts_receivable\": {\n        \"name\": \"Accounts Receivable\",\n        \"sort_code\": \"4\"\n      },\n      \"accounts_payable\": {\n        \"name\": \"Accounts Payable\",\n        \"sort_code\": \"6\"\n      },\n      \"retained_earnings\": {\n        \"name\": \"Retained Earnings\",\n        \"sort_code\": \"8020\"\n      },\n      \"current_year_earnings\": {\n        \"name\": \"Current Year Earnings\",\n        \"sort_code\": \"8030\"\n      }\n    }\n  },\n  \"subscription\": \"tier0\",\n  \"accounting_basis\": \"accrual\"\n}")

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

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/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.sandbox.teal.dev/v0/instance")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"entries_start\": \"2023-11-07T05:31:56Z\",\n  \"name\": \"<string>\",\n  \"coa_template_id\": \"CNmWM3X6AcvRdEwZKxq4bL\",\n  \"custom_coa\": {\n    \"ledgers\": [\n      {\n        \"name\": \"<string>\",\n        \"sort_code\": \"<string>\",\n        \"children\": [\n          \"<unknown>\"\n        ]\n      }\n    ],\n    \"required_ledgers\": {\n      \"uncategorized_inflow\": {\n        \"name\": \"Uncategorized Cash Inflow\",\n        \"sort_code\": \"0\"\n      },\n      \"uncategorized_outflow\": {\n        \"name\": \"Uncategorized Cash Outflow\",\n        \"sort_code\": \"1\"\n      },\n      \"transfers_between_accounts\": {\n        \"name\": \"Transfers Between Accounts\",\n        \"sort_code\": \"2\"\n      },\n      \"opening_balances\": {\n        \"name\": \"Opening Balance Retained Earnings\",\n        \"sort_code\": \"3\"\n      },\n      \"accounts_receivable\": {\n        \"name\": \"Accounts Receivable\",\n        \"sort_code\": \"4\"\n      },\n      \"accounts_payable\": {\n        \"name\": \"Accounts Payable\",\n        \"sort_code\": \"6\"\n      },\n      \"retained_earnings\": {\n        \"name\": \"Retained Earnings\",\n        \"sort_code\": \"8020\"\n      },\n      \"current_year_earnings\": {\n        \"name\": \"Current Year Earnings\",\n        \"sort_code\": \"8030\"\n      }\n    }\n  },\n  \"subscription\": \"tier0\",\n  \"accounting_basis\": \"accrual\"\n}")
  .asString();
require 'uri'
require 'net/http'

url = URI("https://api.sandbox.teal.dev/v0/instance")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"entries_start\": \"2023-11-07T05:31:56Z\",\n  \"name\": \"<string>\",\n  \"coa_template_id\": \"CNmWM3X6AcvRdEwZKxq4bL\",\n  \"custom_coa\": {\n    \"ledgers\": [\n      {\n        \"name\": \"<string>\",\n        \"sort_code\": \"<string>\",\n        \"children\": [\n          \"<unknown>\"\n        ]\n      }\n    ],\n    \"required_ledgers\": {\n      \"uncategorized_inflow\": {\n        \"name\": \"Uncategorized Cash Inflow\",\n        \"sort_code\": \"0\"\n      },\n      \"uncategorized_outflow\": {\n        \"name\": \"Uncategorized Cash Outflow\",\n        \"sort_code\": \"1\"\n      },\n      \"transfers_between_accounts\": {\n        \"name\": \"Transfers Between Accounts\",\n        \"sort_code\": \"2\"\n      },\n      \"opening_balances\": {\n        \"name\": \"Opening Balance Retained Earnings\",\n        \"sort_code\": \"3\"\n      },\n      \"accounts_receivable\": {\n        \"name\": \"Accounts Receivable\",\n        \"sort_code\": \"4\"\n      },\n      \"accounts_payable\": {\n        \"name\": \"Accounts Payable\",\n        \"sort_code\": \"6\"\n      },\n      \"retained_earnings\": {\n        \"name\": \"Retained Earnings\",\n        \"sort_code\": \"8020\"\n      },\n      \"current_year_earnings\": {\n        \"name\": \"Current Year Earnings\",\n        \"sort_code\": \"8030\"\n      }\n    }\n  },\n  \"subscription\": \"tier0\",\n  \"accounting_basis\": \"accrual\"\n}"

response = http.request(request)
puts response.read_body
{
  "id": "<string>",
  "entries_start": "2023-11-07T05:31:56Z",
  "name": "<string>",
  "accounting_package": "platformgl",
  "accounting_basis": "accrual"
}
{
  "message": "<string>",
  "data": "<unknown>",
  "display_message": "<string>"
}
{
  "message": "<string>",
  "data": "<unknown>",
  "display_message": "<string>"
}
{
  "message": "<string>",
  "data": "<unknown>",
  "display_message": "<string>"
}
{
  "message": "<string>",
  "data": "<unknown>",
  "display_message": "<string>"
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer , where is your auth token.

Headers

​
x-teal-agent-id
string<uuid> | null

The agent id

Body

application/json
​
entries_start
string<date-time>
required

The datetime in UTC time from which the API will sync an Instance's accounting data. Transactions or journal entries cannot be entered before this date. The time component is ignored — the value is always stored as start-of-day UTC (00:00:00Z).

Example:

"2024-01-01T00:00:00Z"

​
name
string
required

The name of the business.

Example:

"ACME Goods Inc"

​
coa_template_id
string | null

The ID of the Chart of Accounts Template used to pre-populate the Instance's ledgers.

Example:

"CNmWM3X6AcvRdEwZKxq4bL"

​
custom_coa
InstanceCreateCustomCoa · object | null

A custom COA definition to be used for the created instance.

​
subscription
enum<string>
default:tier0

The Instance's subscription tier.

Available options:
tier0,
tier1,
tier2,
tier3,
tier4
Example:

"tier3"

​
accounting_basis
enum<string> | null

The accounting method used: cash basis or accrual basis.

Available options:
cash,
accrual
Example:

"accrual"

Response

Successful Response

​
id
string
required

The unique ID of the object.

Example:

"RKtPbubK5NcbBsUmU1ktSP"

​
entries_start
string<date-time>
required

The datetime in UTC time from which the API will sync an Instance's accounting data. Transactions or journal entries cannot be entered before this date. The time component is ignored — the value is always stored as start-of-day UTC (00:00:00Z).

Example:

"2024-01-01T00:00:00Z"

​
name
string
required

The name of the business.

Example:

"ACME Goods Inc"

​
subscription
enum<string>
required

The Instance's subscription tier.

Available options:
tier0,
tier1,
tier2,
tier3,
tier4
Example:

"tier3"

​
accounting_package
enum<string>
required

The type of accounting package the Instance uses as the source of truth for their books.

Available options:
platformgl
Example:

"platformgl"

​
accounting_basis
enum<string> | null

The accounting method used: cash basis or accrual basis.

Available options:
cash,
accrual
Example:

"accrual"