cURL

curl --request GET \
  --url https://api.teamfollowup.ai/api/billing/transactions \
  --header 'Authorization: Bearer YOUR_API_KEY'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.teamfollowup.ai/api/billing/transactions', 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.teamfollowup.ai/api/billing/transactions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

	url := "https://api.teamfollowup.ai/api/billing/transactions"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

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

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

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.teamfollowup.ai/api/billing/transactions")

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

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

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

{
  "success": true,
  "data": {
    "window": {
      "from": "2026-08-16",
      "to": "2026-09-14",
      "days": 30
    },
    "transactions": [
      {
        "id": "debit-BKT-7f3a",
        "type": "PURCHASE",
        "occurredAt": "2026-09-12T15:02:11.000Z",
        "description": "Purchased GOLD - 1,000 mins @ $0.340/min",
        "amountUSD": 340,
        "minutes": 1000,
        "ratePerMinute": 0.34,
        "walletEffect": "ADD",
        "cashFlow": "PAID_BY_YOU",
        "subAccount": null,
        "planCode": "GOLD",
        "phoneNumber": null,
        "calls": null,
        "usageDate": null
      },
      {
        "id": "credit-BKT-51c0",
        "type": "SUB_ACCOUNT_TOP_UP",
        "occurredAt": "2026-09-10T09:30:00.000Z",
        "description": "Revenue from Bright Dental - 200 mins @ $0.450/min",
        "amountUSD": 90,
        "minutes": 200,
        "ratePerMinute": 0.45,
        "walletEffect": "DEDUCT",
        "cashFlow": "PAID_TO_YOU",
        "subAccount": {
          "locationId": "loc_9f7a123",
          "name": "Bright Dental"
        },
        "planCode": null,
        "phoneNumber": null,
        "calls": null,
        "usageDate": null
      },
      {
        "id": "phone-BKT-7f3a-1757502000000-+14155550100",
        "type": "PHONE_NUMBER",
        "occurredAt": "2026-09-10T11:00:00.000Z",
        "description": "Monthly renewal of +14155550100",
        "amountUSD": 2,
        "minutes": 5.88,
        "ratePerMinute": 0.34,
        "walletEffect": "DEDUCT",
        "cashFlow": "NONE",
        "subAccount": null,
        "planCode": null,
        "phoneNumber": "+14155550100",
        "calls": null,
        "usageDate": null
      },
      {
        "id": "call-usage-2026-09-09-loc_4c1e882",
        "type": "CALL_USAGE",
        "occurredAt": "2026-09-09T00:00:00.000Z",
        "description": "42 calls from Harbour Roofing paid from your wallet",
        "amountUSD": 26.52,
        "minutes": 78,
        "ratePerMinute": 0.34,
        "walletEffect": "DEDUCT",
        "cashFlow": "NONE",
        "subAccount": {
          "locationId": "loc_4c1e882",
          "name": "Harbour Roofing"
        },
        "planCode": null,
        "phoneNumber": null,
        "calls": 42,
        "usageDate": "2026-09-09"
      }
    ]
  },
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 4,
    "totalPages": 1
  }
}

{
  "success": false,
  "error": "BadRequest",
  "message": "The start date is after the end date. Please swap them and try again.",
  "errors": [
    {
      "field": "dateFromUTC",
      "code": "FieldInvalid",
      "message": "Please check this and try again."
    },
    {
      "field": "dateToUTC",
      "code": "FieldInvalid",
      "message": "Please check this and try again."
    }
  ]
}

{
  "success": false,
  "error": "Unauthorized",
  "message": "Please sign in to continue."
}

{
  "success": false,
  "error": "InsufficientScope",
  "message": "This access key does not allow this action. Please ask your account admin to change its permissions.",
  "requiredScope": "billing:read"
}

{
  "success": false,
  "error": "TooManyRequests",
  "message": "That's a lot at once. Please wait a moment and try again."
}

{
  "success": false,
  "error": "InternalError",
  "message": "Something went wrong on our side. Please try again in a moment.",
  "ref": "3f2b8c1e-7d4a-4f8e-9b6a-2c1d0e5f7a9b"
}

{
  "success": false,
  "error": "CANONICAL_BILLING_READ_UNAVAILABLE",
  "message": "Billing information is temporarily unavailable. Please try again."
}

List billing transactions

Lists everything that moved the agency wallet in a date range, newest first, one page at a time: purchases, refunds of fully unused paid credit, chargebacks, bonus minutes, sub-account top-ups, returned minutes, calls the wallet paid for (one row per sub-account per day), phone numbers and AI co-author messages.

Each row says what it did to the agency wallet (walletEffect) and whether money changed hands (cashFlow).

Allowed customer roles: agency_admin. The agency is the one the credential belongs to; no parameter selects another.

Required API key scope: billing:read.

GET

api

billing

transactions

cURL

curl --request GET \
  --url https://api.teamfollowup.ai/api/billing/transactions \
  --header 'Authorization: Bearer YOUR_API_KEY'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.teamfollowup.ai/api/billing/transactions', 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.teamfollowup.ai/api/billing/transactions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

	url := "https://api.teamfollowup.ai/api/billing/transactions"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

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

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

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.teamfollowup.ai/api/billing/transactions")

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

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

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

{
  "success": true,
  "data": {
    "window": {
      "from": "2026-08-16",
      "to": "2026-09-14",
      "days": 30
    },
    "transactions": [
      {
        "id": "debit-BKT-7f3a",
        "type": "PURCHASE",
        "occurredAt": "2026-09-12T15:02:11.000Z",
        "description": "Purchased GOLD - 1,000 mins @ $0.340/min",
        "amountUSD": 340,
        "minutes": 1000,
        "ratePerMinute": 0.34,
        "walletEffect": "ADD",
        "cashFlow": "PAID_BY_YOU",
        "subAccount": null,
        "planCode": "GOLD",
        "phoneNumber": null,
        "calls": null,
        "usageDate": null
      },
      {
        "id": "credit-BKT-51c0",
        "type": "SUB_ACCOUNT_TOP_UP",
        "occurredAt": "2026-09-10T09:30:00.000Z",
        "description": "Revenue from Bright Dental - 200 mins @ $0.450/min",
        "amountUSD": 90,
        "minutes": 200,
        "ratePerMinute": 0.45,
        "walletEffect": "DEDUCT",
        "cashFlow": "PAID_TO_YOU",
        "subAccount": {
          "locationId": "loc_9f7a123",
          "name": "Bright Dental"
        },
        "planCode": null,
        "phoneNumber": null,
        "calls": null,
        "usageDate": null
      },
      {
        "id": "phone-BKT-7f3a-1757502000000-+14155550100",
        "type": "PHONE_NUMBER",
        "occurredAt": "2026-09-10T11:00:00.000Z",
        "description": "Monthly renewal of +14155550100",
        "amountUSD": 2,
        "minutes": 5.88,
        "ratePerMinute": 0.34,
        "walletEffect": "DEDUCT",
        "cashFlow": "NONE",
        "subAccount": null,
        "planCode": null,
        "phoneNumber": "+14155550100",
        "calls": null,
        "usageDate": null
      },
      {
        "id": "call-usage-2026-09-09-loc_4c1e882",
        "type": "CALL_USAGE",
        "occurredAt": "2026-09-09T00:00:00.000Z",
        "description": "42 calls from Harbour Roofing paid from your wallet",
        "amountUSD": 26.52,
        "minutes": 78,
        "ratePerMinute": 0.34,
        "walletEffect": "DEDUCT",
        "cashFlow": "NONE",
        "subAccount": {
          "locationId": "loc_4c1e882",
          "name": "Harbour Roofing"
        },
        "planCode": null,
        "phoneNumber": null,
        "calls": 42,
        "usageDate": "2026-09-09"
      }
    ]
  },
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 4,
    "totalPages": 1
  }
}

{
  "success": false,
  "error": "BadRequest",
  "message": "The start date is after the end date. Please swap them and try again.",
  "errors": [
    {
      "field": "dateFromUTC",
      "code": "FieldInvalid",
      "message": "Please check this and try again."
    },
    {
      "field": "dateToUTC",
      "code": "FieldInvalid",
      "message": "Please check this and try again."
    }
  ]
}

{
  "success": false,
  "error": "Unauthorized",
  "message": "Please sign in to continue."
}

{
  "success": false,
  "error": "InsufficientScope",
  "message": "This access key does not allow this action. Please ask your account admin to change its permissions.",
  "requiredScope": "billing:read"
}

{
  "success": false,
  "error": "TooManyRequests",
  "message": "That's a lot at once. Please wait a moment and try again."
}

{
  "success": false,
  "error": "InternalError",
  "message": "Something went wrong on our side. Please try again in a moment.",
  "ref": "3f2b8c1e-7d4a-4f8e-9b6a-2c1d0e5f7a9b"
}

{
  "success": false,
  "error": "CANONICAL_BILLING_READ_UNAVAILABLE",
  "message": "Billing information is temporarily unavailable. Please try again."
}

Authorizations

Authorization

string

header

required

Send your API key as Authorization: Bearer YOUR_API_KEY.

Query Parameters

dateFromUTC

string

Start of the window. A UTC ISO 8601 timestamp is canonical; a plain YYYY-MM-DD date is accepted and read as that day at 00:00:00Z. A timestamp must carry Z or an explicit offset, since one without a zone would be read as server-local time and shift the window. An empty string clears the bound. Any other value is refused with 400. Billing windows are whole UTC days, so a timestamp selects the day it falls on. Omit both bounds for the last 30 days. The window can cover at most 366 days.

dateToUTC

string

End of the window, inclusive. Defaults to today. A UTC ISO 8601 timestamp is canonical; a plain YYYY-MM-DD date is accepted and covers that whole day, through 23:59:59.999Z. A timestamp must carry Z or an explicit offset, since one without a zone would be read as server-local time and shift the window. An empty string clears the bound. Any other value is refused with 400. Billing windows are whole UTC days, so a timestamp selects the day it falls on.

type

enum<string>[]

Only these transaction types. Repeat the parameter or separate values with commas.

Available options:

PURCHASE,

REFUND,

CHARGEBACK,

BONUS,

SUB_ACCOUNT_TOP_UP,

MINUTES_RETURNED,

CALL_USAGE,

PHONE_NUMBER,

CO_AUTHOR,

VOICE_SESSION

locationId

string

Only rows that belong to this sub-account. Rows with no sub-account (your own purchases, phone numbers, co-author usage) are left out when this is set.

Minimum string length: 1

page

integer

default:1

Page number, from 1.

Required range: x >= 1

limit

integer

default:50

Rows per page, at most 200.

Required range: 1 <= x <= 200

Response

One page of transactions.

success

boolean

required

Example:

true

data

object

required

Show child attributes

pagination

object

required

Show child attributes

Developer setup

Agents

TFU Live

In-call Capabilities

Campaigns

Master agent

Phone Numbers

Voices

Projects

Calls

Contacts

Native Contacts

Native Calendar

Analytics

Billing

List billing transactions

Authorizations

Query Parameters

Response