Link Search Menu Expand Document

Updated Fri Mar 5th 2021, 12:17 UTC

Index

GET /accounts{?ancestors,descendants,q,type}

Note: This endpoint is still under active development, and may change without warning.

To facilitate a wide variety of the structure of business units within a company, TextUs structures Accounts as a tree hierarchy. The top-level account for a company is referred to as the “primary”, and it has 0 or more children. Those children may have their own children, all referred to as the primary’s “descendants”. The children then have “ancestors”, up to and including the primary.

Users then have Memberships at one or more Accounts within that hierarchy, with separate Roles for each. For example, a User may have the “Admin” role at a lower-level account, and have the “User” role at one higher in the tree.

The representation of the Account returned by this API is a smaller version of normal Account. Since the ancestors and descendants views can include many accounts, this will keep the payloads smaller and focused on relevant information.

Examples

Accounts at which the User has a Membership

To retrieve a list of Accounts that the requesting User is directly a member of, make the request with no query params.

Request

GET /accounts
Example
$ curl -i -H Accept:"application/vnd.textus+jsonld" \
    -H Authorization:"Bearer {token}" \
    -X GET /accounts
    

Response

Status

200

Response Type

AccountCollection

Example
{
  "@type": "AccountCollection",
  "@context": "/contexts/AccountCollection.jsonld",
  "id": "/accounts",
  "members": [
    {
      "@type": "Account",
      "@context": "/contexts/Account.jsonld",
      "id": "/accounts/my_account",
      "name": "Example Account",
      "slug": "my_account",
      "logo": null,
      "phoneNumbers": [
        "(303) 555-1111"
      ],
      "effectiveRole": "admin",
      "type": "standard",
      "analytics": "/accounts/my_account/analytics",
      "inbox": "/my_account/inbox",
      "contacts": "/my_account/contacts",
      "campaigns": "/my_account/campaigns",
      "users": {
        "@type": "hydra:Collection",
        "@context": "/contexts/hydra:Collection.jsonld",
        "id": "/my_account/users",
        "totalItems": 2
      },
      "children": {
        "@type": "hydra:Collection",
        "@context": "/contexts/hydra:Collection.jsonld",
        "id": "/accounts/my_account/children",
        "totalItems": 1,
        "members": []
      }
    }
  ],
  "totalItems": 1,
  "view": {
    "@type": "hydra:PartialCollectionView",
    "@context": "/contexts/hydra:PartialCollectionView.jsonld",
    "id": "/accounts",
    "first": "/accounts",
    "next": null,
    "previous": null
  }
}

Searching Accounts by Name

To search for any Accounts for which the User has visibility (Accounts at which they are a member, plus their ancestors or descendants), use the q query param to search by Account name.

Request

GET /accounts?q=example
Example
$ curl -i -H Accept:"application/vnd.textus+jsonld" \
    -H Authorization:"Bearer {token}" \
    -X GET /accounts?q=example
    

Response

Status

200

Response Type

AccountCollection

Example
{
  "@type": "AccountCollection",
  "@context": "/contexts/AccountCollection.jsonld",
  "id": "/accounts?q=example",
  "members": [
    {
      "@type": "Account",
      "@context": "/contexts/Account.jsonld",
      "id": "/accounts/my_account",
      "name": "Example Account",
      "slug": "my_account",
      "logo": null,
      "phoneNumbers": [
        "(303) 555-1111"
      ],
      "effectiveRole": "admin",
      "type": "standard",
      "analytics": "/accounts/my_account/analytics",
      "inbox": "/my_account/inbox",
      "contacts": "/my_account/contacts",
      "campaigns": "/my_account/campaigns",
      "users": {
        "@type": "hydra:Collection",
        "@context": "/contexts/hydra:Collection.jsonld",
        "id": "/my_account/users",
        "totalItems": 2
      },
      "children": {
        "@type": "hydra:Collection",
        "@context": "/contexts/hydra:Collection.jsonld",
        "id": "/accounts/my_account/children",
        "totalItems": 1,
        "members": []
      }
    }
  ],
  "totalItems": 1,
  "view": {
    "@type": "hydra:PartialCollectionView",
    "@context": "/contexts/hydra:PartialCollectionView.jsonld",
    "id": "/accounts?q=example",
    "first": "/accounts?q=example",
    "next": null,
    "previous": null
  }
}

Searching Accounts by Type

To search for any Accounts for which the User has visibility (Accounts at which they are a member, plus their ancestors or descendants), use the type query param to search by Account type. Viable account types are either standard or organization.

Request

GET /accounts?type=standard
Example
$ curl -i -H Accept:"application/vnd.textus+jsonld" \
    -H Authorization:"Bearer {token}" \
    -X GET /accounts?type=standard
    

Response

Status

200

Response Type

AccountCollection

Example
{
  "@type": "AccountCollection",
  "@context": "/contexts/AccountCollection.jsonld",
  "id": "/accounts?type=standard",
  "members": [
    {
      "@type": "Account",
      "@context": "/contexts/Account.jsonld",
      "id": "/accounts/my_account",
      "name": "Example Account",
      "slug": "my_account",
      "logo": null,
      "phoneNumbers": [
        "(303) 555-1111"
      ],
      "effectiveRole": "admin",
      "type": "standard",
      "analytics": "/accounts/my_account/analytics",
      "inbox": "/my_account/inbox",
      "contacts": "/my_account/contacts",
      "campaigns": "/my_account/campaigns",
      "users": {
        "@type": "hydra:Collection",
        "@context": "/contexts/hydra:Collection.jsonld",
        "id": "/my_account/users",
        "totalItems": 2
      },
      "children": {
        "@type": "hydra:Collection",
        "@context": "/contexts/hydra:Collection.jsonld",
        "id": "/accounts/my_account/children",
        "totalItems": 1,
        "members": []
      }
    }
  ],
  "totalItems": 1,
  "view": {
    "@type": "hydra:PartialCollectionView",
    "@context": "/contexts/hydra:PartialCollectionView.jsonld",
    "id": "/accounts?type=standard",
    "first": "/accounts?type=standard",
    "next": null,
    "previous": null
  }
}

Showing Accounts within the Account hierarchy

Since a User may belong multiple accounts within a hierarchy under the primary, it is useful to show where within that heirarchy their Accounts are positioned. The ancestors=true parameter will cause this endpoint to return the “primary” as the top-level, and populate the children fields down to the lowest level at which the User has a Membership.

Request

GET /accounts?ancestors=true
Example
$ curl -i -H Accept:"application/vnd.textus+jsonld" \
    -H Authorization:"Bearer {token}" \
    -X GET /accounts?ancestors=true
    

Response

Status

200

Response Type

AccountCollection

Example
{
  "@type": "AccountCollection",
  "@context": "/contexts/AccountCollection.jsonld",
  "id": "/accounts?ancestors=true",
  "members": [
    {
      "@type": "Account",
      "@context": "/contexts/Account.jsonld",
      "id": "/accounts/my_account",
      "name": "Example Account",
      "slug": "my_account",
      "logo": null,
      "phoneNumbers": [
        "(303) 555-1111"
      ],
      "effectiveRole": null,
      "type": "standard",
      "analytics": "/accounts/my_account/analytics",
      "inbox": "/my_account/inbox",
      "contacts": "/my_account/contacts",
      "campaigns": "/my_account/campaigns",
      "users": {
        "@type": "hydra:Collection",
        "@context": "/contexts/hydra:Collection.jsonld",
        "id": "/my_account/users",
        "totalItems": 2
      },
      "children": {
        "@type": "hydra:Collection",
        "@context": "/contexts/hydra:Collection.jsonld",
        "id": "/accounts/primary/children",
        "members": [
          {
            "@type": "Account",
            "@context": "/contexts/Account.jsonld",
            "id": "/accounts/my_account",
            "name": "Example Account",
            "slug": "my_account",
            "logo": null,
            "phoneNumbers": [
              "(303) 555-1111"
            ],
            "effectiveRole": "admin",
            "type": "standard",
            "analytics": "/accounts/my_account/analytics",
            "inbox": "/my_account/inbox",
            "contacts": "/my_account/contacts",
            "campaigns": "/my_account/campaigns",
            "users": {
              "@type": "hydra:Collection",
              "@context": "/contexts/hydra:Collection.jsonld",
              "id": "/my_account/users",
              "totalItems": 2
            },
            "children": {
              "@type": "hydra:Collection",
              "@context": "/contexts/hydra:Collection.jsonld",
              "id": "/accounts/my_account/children",
              "totalItems": 1,
              "members": []
            }
          }
        ],
        "totalItems": 1
      }
    }
  ],
  "totalItems": 1,
  "view": {
    "@type": "hydra:PartialCollectionView",
    "@context": "/contexts/hydra:PartialCollectionView.jsonld",
    "id": "/accounts?ancestors=true",
    "first": "/accounts?ancestors=true",
    "next": null,
    "previous": null
  }
}

Showing Accounts with their descendants

Since a User may be an admin of several Accounts, its useful to fetch those Accounts in a single request. By passing descendants=true as a query param, the response will show the accounts at which they have a membership at the root, and all the Accounts that are children as a tree.

Request

GET /accounts?descendants=true
Example
$ curl -i -H Accept:"application/vnd.textus+jsonld" \
    -H Authorization:"Bearer {token}" \
    -X GET /accounts?descendants=true
    

Response

Status

200

Response Type

AccountCollection

Example
{
  "@type": "AccountCollection",
  "@context": "/contexts/AccountCollection.jsonld",
  "id": "/accounts?descendants=true",
  "members": [
    {
      "@type": "Account",
      "@context": "/contexts/Account.jsonld",
      "id": "/accounts/my_account",
      "name": "Example Account",
      "slug": "my_account",
      "logo": null,
      "phoneNumbers": [
        "(303) 555-1111"
      ],
      "effectiveRole": "admin",
      "type": "standard",
      "analytics": "/accounts/my_account/analytics",
      "inbox": "/my_account/inbox",
      "contacts": "/my_account/contacts",
      "campaigns": "/my_account/campaigns",
      "users": {
        "@type": "hydra:Collection",
        "@context": "/contexts/hydra:Collection.jsonld",
        "id": "/my_account/users",
        "totalItems": 2
      },
      "children": {
        "@type": "hydra:Collection",
        "@context": "/contexts/hydra:Collection.jsonld",
        "id": "/accounts/primary/children",
        "members": [
          {
            "@type": "Account",
            "@context": "/contexts/Account.jsonld",
            "id": "/accounts/my_account",
            "name": "Example Account",
            "slug": "my_account",
            "logo": null,
            "phoneNumbers": [
              "(303) 555-1111"
            ],
            "effectiveRole": "admin",
            "type": "standard",
            "analytics": "/accounts/my_account/analytics",
            "inbox": "/my_account/inbox",
            "contacts": "/my_account/contacts",
            "campaigns": "/my_account/campaigns",
            "users": {
              "@type": "hydra:Collection",
              "@context": "/contexts/hydra:Collection.jsonld",
              "id": "/my_account/users",
              "totalItems": 2
            },
            "children": {
              "@type": "hydra:Collection",
              "@context": "/contexts/hydra:Collection.jsonld",
              "id": "/accounts/my_account/children",
              "totalItems": 1,
              "members": []
            }
          }
        ],
        "totalItems": 1
      }
    }
  ],
  "totalItems": 1,
  "view": {
    "@type": "hydra:PartialCollectionView",
    "@context": "/contexts/hydra:PartialCollectionView.jsonld",
    "id": "/accounts?descendants=true",
    "first": "/accounts?descendants=true",
    "next": null,
    "previous": null
  }
}

Table of contents


© 2021 TextUs