List your accounts

Overview

Get every account under your partner, with owner email, status, location count, active-plan count, and current plan name. Add call_for=dropdown to get a simple name/ID list instead, handy for populating a menu in your own app.

Use this to build an account list in your dashboard, or to find an account's id.

You'll need a partner token. Results are paginated and can be sorted, searched, and filtered to accounts with an active plan. What you see is limited to the accounts and locations assigned to your user, so two users at the same partner can get different lists. You can filter to one account by our id or your client_account_id; an id outside your accounts returns an empty page, not an error.

Returns one entry per account, including the sub-partner it belongs to if any.

Prerequisites

A Partner token. See Authentication.

Base URL

Environment	URL
Production	`https://production-api.shoutaboutus.com`
Development	`https://development-api.shoutaboutus.com`

Endpoint

GET /api/v1/partner/account/list

Authentication

Partner token

Lists the accounts in your partner's tree, including those under your sub-partners.
A user who is assigned to particular accounts or locations sees only those accounts.
account_id must be inside your account tree; otherwise 422. A client_account_id that isn't one of yours returns an empty page.
Any other token gets 403.

Rate limit

This endpoint has no rate limit.

Request parameters

Parameter	In	Type	Required	Description
`limit`	query	integer	No	Page size, 10 to 100. Default 10. Values below 10 are raised to 10; above 100 returns `422`. With `call_for=dropdown`, at most 50 entries are returned, and with no `limit` the whole list is returned.
`page`	query	integer	No	Page number. Default 1.
`sort_field`	query	string	No	`company_name`, `email`, `status` or `plan_name`. Default `company_name`.
`sort_by`	query	string	No	`asc` or `desc` (either case). Default `asc`.
`search_field`	query	string	No	`company_name`, `email`, `status` or `plan_name`. Use with `search_value`. `company_name` also matches your `client_account_id`.
`search_value`	query	string	No	The text to search for (part of the value is enough). With `search_field=status`, the exact `status` number.
`active_plan`	query	integer	No	`1` to list only accounts that have a location on an active plan.
`call_for`	query	string	No	`dropdown` to get a label/value list instead of the paginated list.
`account_id`	query	integer	No	Return only this account (our id).
`client_account_id`	query	string	No	Return only the account with this id of yours. Max 255 characters.

Request body

None.

Request payload

None.

Response body

The paginated list. Each entry in data is one account.

Field	Type	Description
`data`	array	The accounts on this page.
`data[].id`	integer	The account's id.
`data[].company_name`	string	The account's name.
`data[].email`	string	The account owner's email.
`data[].account_status`	string	`Active`, `Inactive` or `Paused`, from the owner's status.
`data[].status`	integer	The owner's status as a number: `1` active, `0` inactive; any other value is paused.
`data[].total_locations`	integer	The number of the account's active or pending locations.
`data[].store_ids`	array of integers	The ids of those locations.
`data[].total_active_plan`	integer	The number of the account's locations with an active or expired plan.
`data[].plan_name`	string or null	The account's plan, or `null` when it has none.
`data[].client_account_id`	string or null	Your own id for the account.
`data[].sub_partner_name`	string or null	The sub-partner the account belongs to, or `null` when it sits directly under your partner.
`links`	object	URLs of the `first`, `last`, `prev` and `next` pages (`null` when there's no such page).
`meta`	object	Paging details: `current_page`, `from`, `last_page`, `links`, `path`, `per_page`, `to` and `total`.

With call_for=dropdown, the payload is inside data instead:

Field	Type	Description
`status`	string	`success`.
`response`	array	The accounts. When there's more than one and no `search_value`, the first entry is `{"label": "All", "value": ""}`.
`response[].label`	string	The account's name, plus `- <client_account_id>` when it has one.
`response[].value`	integer	The account's id.

Response payload

{
  "data": [
    {
      "id": 5994,
      "company_name": "Acme Coffee",
      "email": "[email protected]",
      "account_status": "Active",
      "status": 1,
      "total_locations": 2,
      "store_ids": [3007, 3008],
      "total_active_plan": 2,
      "plan_name": "Growth — Unlimited",
      "client_account_id": "docs-test-acct-001",
      "sub_partner_name": null
    }
  ],
  "links": {
    "first": "https://production-api.shoutaboutus.com/api/v1/partner/account/list?page=1",
    "last": "https://production-api.shoutaboutus.com/api/v1/partner/account/list?page=3",
    "prev": null,
    "next": "https://production-api.shoutaboutus.com/api/v1/partner/account/list?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 3,
    "links": [
      { "url": null, "label": "&laquo; Previous", "page": null, "active": false },
      { "url": "https://production-api.shoutaboutus.com/api/v1/partner/account/list?page=1", "label": "1", "page": 1, "active": true },
      { "url": "https://production-api.shoutaboutus.com/api/v1/partner/account/list?page=2", "label": "Next &raquo;", "page": 2, "active": false }
    ],
    "path": "https://production-api.shoutaboutus.com/api/v1/partner/account/list",
    "per_page": 10,
    "to": 10,
    "total": 24
  }
}

Examples

Success payload

With call_for=dropdown:

{
  "data": {
    "status": "success",
    "response": [
      { "label": "All", "value": "" },
      { "label": "Acme Brand - ACC-001", "value": 6021 },
      { "label": "Acme Coffee - docs-test-acct-001", "value": 5994 }
    ]
  }
}

Error payload

403 Not a partner

{
  "message": "Forbidden",
  "status": "error",
  "errors": "Response scribe sub-partner user can access this endpoint."
}

422 Page size too large

{
  "message": "The limit field must not be greater than 100.",
  "errors": {
    "limit": ["The limit field must not be greater than 100."]
  }
}

422 Account outside your tree

{
  "message": "The selected account id does not belong to your company hierarchy.",
  "errors": {
    "account_id": ["The selected account id does not belong to your company hierarchy."]
  }
}

Status	Meaning
`200`	The accounts.
`401`	The token is missing, expired or invalid.
`403`	The token isn't a Partner token.
`422`	A parameter failed validation, e.g. `limit` above 100 or an `account_id` outside your tree.
`500`	Unexpected server error.

Example request

curl --request GET \
  --url "https://production-api.shoutaboutus.com/api/v1/partner/account/list?limit=10&page=1&sort_field=company_name&sort_by=asc" \
  --header 'Authorization: Bearer <bearer-token>' \
  --header 'Accept: application/json'