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
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
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
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
}
}
Searching Accounts by Legal Entity
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
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
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
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
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
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
}
}