Accounts

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

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.

Note: Most API endpoints documented here are scoped to resources belonging to a specific Account using the placeholder value :account_slug in the URLs. In our examples, we use "my_account" as the value of that placeholder. Whenever you see :account_slug in the documentation, you should substitute it for the slug value of your own Account(s).

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 Body

{
  "@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 Body

{
  "@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 Body

{
  "@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
  }
}

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 legal query param to search for accounts that have the setting legal_entity enabled.

Request

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

Response

Status

200

Response Type

AccountCollection

Example Body

{
  "@type": "AccountCollection",
  "@context": "/contexts/AccountCollection.jsonld",
  "id": "/accounts?legal=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": "orgnization",
      "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?legal=true",
    "first": "/accounts?legal=true",
    "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 Body

{
  "@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 Body

{
  "@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
  }
}

Searching Accounts by Phone

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 additionally search by Account phone number.

Request

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

Response

Status

200

Response Type

AccountCollection

Example Body

{
  "@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 Slug

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 slug query param to search by Account slug.

Request

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

Response

Status

200

Response Type

AccountCollection

Example Body

{
  "@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?slug=my_account",
    "first": "/accounts?slug=my_account",
    "next": null,
    "previous": null
  }
}

Table of contents


© 2024 TextUs