List accounts

GEThttps://app.shuttleglobal.com/c/api/instances/{instance_key}/accounts

Language

Credentials

Secret key

Instance keyRemember on this device

Kept in this browser tab unless you tick Remember; don't on a shared computer. Use keys from a sandbox account to test without moving money.

Parameters

Query

criteriaorderexpandlimitoffset

cURL request

curl --request GET \
  --url https://app.shuttleglobal.com/c/api/instances/YOUR_INSTANCE_KEY/accounts \
  --header 'Authorization: Basic <base64 of SECRET_KEY:>'

const url = 'https://app.shuttleglobal.com/c/api/instances/YOUR_INSTANCE_KEY/accounts';
const options = {method: 'GET', headers: {Authorization: 'Basic <base64 of SECRET_KEY:>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

import requests

url = "https://app.shuttleglobal.com/c/api/instances/YOUR_INSTANCE_KEY/accounts"

headers = {"Authorization": "Basic <base64 of SECRET_KEY:>"}

response = requests.get(url, headers=headers)

print(response.json())

<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://app.shuttleglobal.com/c/api/instances/YOUR_INSTANCE_KEY/accounts', [
  'headers' => [
    'Authorization' => 'Basic <base64 of SECRET_KEY:>',
  ],
]);

echo $response->getBody();

require 'uri'
require 'net/http'

url = URI("https://app.shuttleglobal.com/c/api/instances/YOUR_INSTANCE_KEY/accounts")

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

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Basic <base64 of SECRET_KEY:>'

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

package main

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

func main() {

  url := "https://app.shuttleglobal.com/c/api/instances/YOUR_INSTANCE_KEY/accounts"

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

  req.Header.Add("Authorization", "Basic <base64 of SECRET_KEY:>")

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

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

  fmt.Println(res)
  fmt.Println(string(body))

}

const url = 'https://app.shuttleglobal.com/c/api/accounts';
const options = {method: 'GET', headers: {Authorization: 'Bearer YOUR_ACCESS_TOKEN'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://app.shuttleglobal.com/c/api/accounts', [
  'headers' => [
    'Authorization' => 'Bearer YOUR_ACCESS_TOKEN',
  ],
]);

echo $response->getBody();

require 'uri'
require 'net/http'

url = URI("https://app.shuttleglobal.com/c/api/accounts")

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

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

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

package main

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

func main() {

  url := "https://app.shuttleglobal.com/c/api/accounts"

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

  req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")

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

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

  fmt.Println(res)
  fmt.Println(string(body))

}

Response

List of accounts

{
  "accounts": [
    {
      "address": {},
      "bolton_values": {},
      "channels": [
        "string"
      ],
      "code": "string",
      "company": "string",
      "created": "2026-01-01T12:00:00Z",
      "created_session": "string",
      "crm": "string",
      "crm_key": "string",
      "disconnected_account": true,
      "divisions": [
        "string"
      ],
      "email": "string",
      "first_name": "string",
      "full_address": "string",
      "giftaid_ineligible": true,
      "id": "string",
      "initiatives": [
        "string"
      ],
      "last_name": "string",
      "last_transacted": "2026-01-01T12:00:00Z",
      "last_transaction": "string",
      "locale": "string",
      "metadata": {},
      "name": "string",
      "phone": "string",
      "status": "ACTIVE",
      "tags": "string",
      "timezone": "string",
      "updated": "2026-01-01T12:00:00Z",
      "updated_session": "string",
      "v": 0
    }
  ],
  "meta": {
    "limit": 0,
    "offset": 0,
    "total": 0
  }
}

GET

/accounts

Search and list account objects with various filtering criteria.

The search criteria syntax supports various operators:

= Exact match (multiple values with ; for IN)
~= Partial match (contains)
!=, >=, >, <, <= Comparisons
<> Between (separate with ;)
! Is null
!! Is not null

Multiple criteria can be combined with , (AND). See project README.md for detailed examples and usage.

Authorizations

basicAuth
bearerAuth

Parameters

Query Parameters

criteria

string

Search criteria for filtering accounts. Available fields: id, first_name, last_name, email, phone, company, crm_key, crm, channel, division, tags, last_transacted, created, updated

Examples:

email=user@example.com
status=ACTIVE;PENDING
company~=Tech
created<>2024-01-01;2024-12-31
status=ACTIVE,email~=example.com

order

string

Sort order for results. Supports any field that criteria supports. Defaults to created:desc if not specified. Append :desc for descending order. Separate multiple order fields with commas.

Examples:

order=updated
order=last_name:desc
order=company,created:desc

expand

string

Fields to expand into full objects. Separate multiple fields with commas.

Available fields:

last_transaction (transaction object)
created_session (session object)
updated_session (session object)

Example: expand=last_transaction,created_session

limit

integer

Number of records to return: 20 if not set, at most 1000.

offset

integer

Number of records to skip before the first one returned. offset + limit can’t exceed 5000; to read further, page by a field such as created instead. See Paging through results.

Responses

200

List of accounts

application/json

object

accounts

Array<object>

A customer account object. Contains all information about a customer including their contact details, status, and metadata.

IMPORTANT: The bolton_values field is managed internally by the system and should not be modified or referenced directly in tests or integrations. Always use the standard top-level fields (company, email, phone, etc.) when creating, updating, or querying accounts.

object

address

object

Address fields. All fields are optional and any values are accepted to prevent interrupting payments due to address validation issues. Field behavior:

When updating an address, the entire address object is replaced with the new values
To clear/null out all address fields, set each field to an empty string Client applications can implement their own validation if needed.

object

country

string

Country code (any format accepted). Set to empty string to clear.

line1

string

First line of the address. Set to empty string to clear.

line2

string

Second line of the address. Set to empty string to clear.

line3

string

Third line of the address. Set to empty string to clear.

line4

string

City/Town. Set to empty string to clear.

line5

string

Postcode/ZIP. Set to empty string to clear.

line6

string

State/Region. Set to empty string to clear.

bolton_values

object

Enterprise Feature: Internal system values. This field is only relevant for enterprise customers and should be ignored by other users.

object

key

additional properties

any

channels

Array<string>

List of channels that have permission to see this account. When an account makes a payment against a channel, they are automatically added to that channel.

code

string

Account code

company

string

Company name

created

string · date-time

Account creation timestamp

created_session

string

Session ID when the account was created

Pattern /^ses_[0-9]+_[0-9]+$/

crm

string

Enterprise Feature: The CRM system identifier. This field is only relevant for enterprise customers and should be ignored by other users.

crm_key

string

Your identifier for the account

disconnected_account

boolean

Enterprise Feature: Indicates if this account is disconnected from the enterprise CRM system. This field is only relevant for enterprise customers and should be ignored by other users.

divisions

Array<string>

List of divisions that have permission to see this account. A division can be added to this list directly via the API, or is automatically added when an account makes a payment against either (1) a channel that belongs to the division or (2) an initiative that belongs to the division.

email

string

Email address. Invalid addresses are accepted to prevent interrupting payments due to email validation issues. Client applications can implement their own validation if needed.

first_name

string

First name of the account holder

full_address

string

Formatted full address

giftaid_ineligible

boolean

Indicates the account is excluded from Gift Aid eligibility (GB donations)

string

Unique identifier for the account

Pattern /^acc_[0-9]+_[0-9]+$/

initiatives

Array<string>

List of initiatives that this account has performed payments against. When an account makes a payment against an initiative, it is automatically added to this list.

last_name

string

Last name of the account holder

last_transacted

string · date-time

Timestamp of last transaction

last_transaction

string

ID of last transaction

locale

string

Locale of the user

metadata

object

Custom key-value pairs stored on the account

object

key

additional properties

string

name

string

Full name of the account holder

phone

string

Phone number. Any format is accepted to prevent interrupting payments due to phone validation issues. Client applications can implement their own validation if needed.

status

string · enum

Account status

Allowed values: ACTIVE TEMP

tags

string

CSV of tags/references

timezone

string

Timezone in IANA format

updated

string · date-time

Last update timestamp

updated_session

string

Session ID when the account was last updated

Pattern /^ses_[0-9]+_[0-9]+$/

integer

Object version for optimistic concurrency control

meta

object

limit

integer

offset

integer

total

integer

400

Bad request

application/json

Every error has a code and a message. Some add more fields alongside them, with detail about the error.

object

code

string

The error code, for example VALIDATION_ERROR, INVALID, INVALID_REQUEST, UNAUTHORIZED, FORBIDDEN or NOT_FOUND. Program against this, not the message.

message

string

What went wrong, in words, for logs and support.

401

Invalid credentials (authentication is validated before instance key)

application/json

Every error has a code and a message. Some add more fields alongside them, with detail about the error.

object

code

string

The error code, for example VALIDATION_ERROR, INVALID, INVALID_REQUEST, UNAUTHORIZED, FORBIDDEN or NOT_FOUND. Program against this, not the message.

message

string

What went wrong, in words, for logs and support.

Example

{
  "code": "UNAUTHORIZED",
  "message": "Unauthorised"
}

404

Instance not found (only checked after successful authentication)

application/json

Every error has a code and a message. Some add more fields alongside them, with detail about the error.

object

code

string

The error code, for example VALIDATION_ERROR, INVALID, INVALID_REQUEST, UNAUTHORIZED, FORBIDDEN or NOT_FOUND. Program against this, not the message.

message

string

What went wrong, in words, for logs and support.

Was this page helpful?