NAV
javascript

Introduction

Welcome to tatag.cc's API.

Resource Orientation

Examples of the supported navigational approaches

api.loadConcept('my-memberships') 
.then(okHandler, errHandler) 

To get a target resource, the client looks in the root resource to fill-in applicable URL-templates or to follow directions along a given sequence of link relations. This approach is tolerant of changes in the URL structure and media type, and may be likened to always asking for directions to a certain warehous item - you will be able to find something even if there are changes to the aisle-number or the corridor layout. The API consumer will also be more likely to be able to navigate different warehouses.

Methods

Resources may be linked to forms for creating, editing, or otherwise affecting its state. API clients should not assume that a particular resource will always support the same set of methods. Instead, a client should check for the existence of any of the following form links before initiating the corresponding display or action options.

Tolerance

The client must be programmed with tolerance in mind, to accomodate potential variations in labels and methods as seen above. Many of these concerns are automatically handled by generic API clients, such as for the Phlat profile. We recommend using generic media-type or profile clients to minimize the effort in getting started and to increase the long-term stability of the consumer application.

The API consumer should gracefully handle the following:

Versioning

(... TBD ...)

Authentication

If your application is not acting on behalf of a user, then simply use HTTP Basic Auth.

If your application is acting on behalf of a user, such as displaying personal, team, and admin resources, then you would need to do the Oauth dance of passing around token value and secret in the URL. I'll document this dance based on demand.

Public Resources

These resources do not require a user to be logged-in.

public-brands


api.loadConcept('public-brands');

Status 200

{
    "pageOrder": "asc",
    "itemsLimit": 50,
    "collectionOf": "brand",
    "pageOf": "/brand/collection",
    "@id": "/brand/collection",
    "@type": "brandCollection",
    "numBrands": 13,
    "earliest": "2015-01-05 11:53:31",
    "latest": "2015-11-18 20:21:32",
    "brand": [
        {
            "brand_id": 104,
            "name": "abc",
            "description": "another description -1455687238",
            "created": "2015-01-05 11:53:31",
            "updated": "2016-02-16 21:33:59",
            "ended": null,
            "url": null,
            "advisor": 0,
            "type_system": "for-profit",
            "type_id": 9,
            "country_code": "USA",
            "area_code": 206,
            "@id": "/brand/104/about"
        },
        {
            "brand_id": 105,
            "name": "def",
            "description": "for testing",
            "created": "2015-01-05 11:53:33",
            "updated": null,
            "ended": null,
            "url": null,
            "advisor": 0,
            "type_system": "for-profit",
            "type_id": 9,
            "country_code": "USA",
            "area_code": 206,
            "@id": "/brand/105/about"
        },
        {
            "brand_id": 106,
            "name": "~Amazon.com, Boren Avenue North, Seattle, WA, United States",
            "description": "This is a simulated brand to be used for testing the tatag system.",
            "created": "2015-08-08 18:38:54",
            "updated": null,
            "ended": null,
            "url": null,
            "advisor": null,
            "type_system": "sim",
            "type_id": 10,
            "country_code": "USA",
            "area_code": 206,
            "@id": "/brand/106/about"
        }
    ],
    "add": "/form/brand-registration"
}

A collection or paged list of public-brand.

PropertyTypeDescription
@idstring...
@typestring...
collectionOfstringThe term used for the collection item. For example, instead of promos.items, you could use promos.promo or promos[promos.collectionOf].
earlieststring...
itemsLimitintegerThe maximum number of items that is returned in a collection page. To request more than the itemsLimit, make subsequent requests using the collection's 'next' or 'prev' link.
lateststring...
numBrandsinteger...
pageOfstringThe '@id' of the collection to which the current page belongs. In other words, this is the link to the default collection resource without pagination.
pageOrderstringEither 'asc' or 'desc' based on item id's.
Links
brandlinkThe currency issuer related to this resource.
Forms
addformA form for adding a resource to a collection, or for adding to a resource's tracked quantity.

public-brand


api.loadConcept('public-brand');

Status 200

[
    {
        "brand_id": 104,
        "name": "abc",
        "description": "another description -1455687238",
        "created": "2015-01-05 11:53:31",
        "updated": "2016-02-16 21:33:59",
        "ended": null,
        "url": null,
        "advisor": 0,
        "type_system": "for-profit",
        "type_id": 9,
        "country_code": "USA",
        "area_code": 206,
        "@id": "/brand/104/about"
    }
]

A registered team that issues its own currency.

PropertyTypeDescription
@idstring...
advisorinteger...
area_codeintegerThe phone area code where a brand is located. (optional, self-reported)
brand_idinteger(deprecated)
country_codestringThe ISO3 code of a brand location.
createdstringThe date and time when a resource was created, in the form of `YYYY-MM-DD hh:mm:ss`.
descriptionstring...
endedNULLThe date of resource or relation deactivation, formatted as `YYYY-MM-DD hh:mm:ss`.
namestringThe name of the resource.
type_idintegerA brand's self-reported classification.
type_systemstringThe classification system that is used to determine the brand type_id value.
updatedstringThe UNIX timestamp when a resource was last updated.
urlNULLA link to a web page or image, typically not considered as an API data and therefore not expected to be dereferenced as part of the payload but instead opened as an external link or used in HTML representations.

public-promos


api.loadConcept('public-promos');

Status 200

{
    "pageOrder": "desc",
    "itemsLimit": 50,
    "collectionOf": "promo",
    "pageOf": "/promo/collection",
    "@type": "promoCollection",
    "@id": "/promo/collection",
    "popular": "/promo/popular",
    "promo": [
        "/promo/15",
        "/promo/14",
        "/promo/13"
    ],
    "search": "/form/promo-search"
}

A collection or paged list of public-promo.

PropertyTypeDescription
@idstring...
@typestring...
collectionOfstringThe term used for the collection item. For example, instead of promos.items, you could use promos.promo or promos[promos.collectionOf].
itemsLimitintegerThe maximum number of items that is returned in a collection page. To request more than the itemsLimit, make subsequent requests using the collection's 'next' or 'prev' link.
pageOfstringThe '@id' of the collection to which the current page belongs. In other words, this is the link to the default collection resource without pagination.
pageOrderstringEither 'asc' or 'desc' based on item id's.
Links
popularlink...
promolinkA brand promotion, used to advertise anything that could be the target of a payment.
Forms
searchform...

public-promo


api.loadConcept('public-promo');

Status 200

[
    {
        "promo_id": 15,
        "name": "product promo {hex}",
        "description": "a brand 104 promo {hex}",
        "amount": 5.43,
        "imageURL": null,
        "infoURL": null,
        "created": "2016-02-16 21:34:00",
        "updated": 1455687240,
        "expires": "2016-12-31 00:00:00",
        "keyword": "ad",
        "by_all_limit": 25,
        "by_brand_limit": 5,
        "by_user_limit": 2,
        "by_user_wait": 24,
        "id": 15,
        "@id": "/promo/15",
        "@type": "promo",
        "edit": "/form/promo-edit",
        "brand": "/brand/104/about",
        "promoPage": "http://tatag.dev/ad/15",
        "code": "ad-15",
        "payURL": "http://tatag.dev/for/ad-15",
        "imageTemplate": "/ui/logo.php"
    }
]

Anything that a participant could pay for, such as for purchasing products, funding nonprofit campaigns, or supporting team projects with donations.

PropertyTypeDescription
@idstring...
@typestring...
amountdoubleA numeric value that quantifies an important aspect of a resource. For example, in the context of a promo or transaction record, the amount may be a product price or a suggested donation amount.
by_all_limitintegerThis is a weekly limit on the total inflow transaction amount for a given account or usage for a given product, regardless of the payor's brand or user id. This is similar to coupon restrictions, allowing your brand to set limits on transactions and also to combat spammy payment offers.
by_brand_limitintegerA weekly limit on total inflow transaction amount for a given account or usage for a given promo, based on the payor's brand id. This is similar to coupon restrictions, allowing your brand to set limits on transactions and also to combat spammy payment offers.
by_user_limitintegerA weekly limit on total inflow transaction amount for a given account or usage for a given promo, based on the payor's user id. This is similar to coupon restrictions, allowing your brand to set limits on transactions and also to combat spammy payment offers.
by_user_waitintegerHow long a user must wait after using a promo, before that user can reuse the same promo.
codestringAn alpha-numeric string that a payment recipient shares with a payor to authorize a payment or promo use.
createdstringThe date and time when a resource was created, in the form of `YYYY-MM-DD hh:mm:ss`.
descriptionstring...
expiresstringThe date after which a given resource will no longer be available. For example, a promo may expire after a week.
idintegerA numeric identifier for a resource, that is unique for a given resource type.
imageTemplatestringIf given, a user interface provider may use this resource to display a brand icon or promo image.
imageURLNULLIf given, a user interface provider may use this link to display a brand icon or promo image.
infoURLNULLExternal web page about a resource.
keywordstringIn the context of a relay, this is the prefix to be used with a relay id, such as the 'food-' in the relay token value of 'food-645'. This keyword is assigned by the user when creating a promo, and also helps to counter (but not prevent) spammy transaction offers by making it harder to guess the full value of a relay token.
namestringThe name of the resource.
payURLstringA URL that, when clicked, is intended to automatically open the tatag.cc wallet of a payor.
promoPagestringThe tatag.cc-hosted web page about the promo. An infoURL, when available, should be preferred as an external link.
promo_idinteger(deprecated)
updatedintegerThe UNIX timestamp when a resource was last updated.
Links
brandlinkThe currency issuer related to this resource.
Forms
editformA form for updating a resource.

api.loadConcept('public-promos-popular');

Status 200

{
    "pageOrder": "desc",
    "itemsLimit": 50,
    "collectionOf": "promo",
    "pageOf": "/promo/popular",
    "@type": "promoPopular",
    "@id": "/promo/popular",
    "promo": [
        "/promo/1"
    ]
}

blah blah blah

PropertyTypeDescription
@idstring...
@typestring...
collectionOfstringThe term used for the collection item. For example, instead of promos.items, you could use promos.promo or promos[promos.collectionOf].
itemsLimitintegerThe maximum number of items that is returned in a collection page. To request more than the itemsLimit, make subsequent requests using the collection's 'next' or 'prev' link.
pageOfstringThe '@id' of the collection to which the current page belongs. In other words, this is the link to the default collection resource without pagination.
pageOrderstringEither 'asc' or 'desc' based on item id's.
Links
promolinkA brand promotion, used to advertise anything that could be the target of a payment.

Personal Resources

These are resources that belong to the current user and are meant for private viewing. These resources are inteded to be used for wallet type applications, and in order for such applications to act on behalf of a user, oauth-type authentication is required.

my-me


api.loadConcept('my-me');

Status 200

{
    "@id": "/user/21",
    "@type": "user",
    "user_id": 21,
    "memberships": "/user/21/memberships",
    "holdings": "/user/21/accounts",
    "ratings": "/user/21/ratings",
    "about": "/user/21/about",
    "name": "User One",
    "login_provider": "gp",
    "teams": "/user/21/teams",
    "issuers": "/user/21/brands",
    "apps": "/user/21/apps",
    "promoSearch": "/form/promo-search",
    "id": 21
}

The currently logged-in user.

PropertyTypeDescription
@idstring...
@typestring...
idintegerA numeric identifier for a resource, that is unique for a given resource type.
login_providerstringThe identity provider for the currently logged-in user, usually an OpenId provider.
namestringThe name of the resource.
promoSearchstring...
user_idinteger(deprecated)
Links
aboutlinkInformation about the current resource.
appslink...
holdingslinkA collection of accountholdings.
issuerslinkA collection of brand-resources to which a user has a member role of admin.
membershipslinkA collection of team membership information for a user.
ratingslinkA collection of 'rating'.
teamslinkA collection of brand-resources to which a user belongs as a member.

my-memberships


api.loadConcept('my-memberships');

Status 200

{
    "@type": "userMemberships",
    "user_id": 21,
    "@id": "/user/21/memberships",
    "collectionOf": "memberships",
    "membership": [
        "/user/21/memberships?member_id=53"
    ]
}

The current user's collection of membership information.

PropertyTypeDescription
@idstring...
@typestring...
collectionOfstringThe term used for the collection item. For example, instead of promos.items, you could use promos.promo or promos[promos.collectionOf].
user_idinteger(deprecated)
Links
membershiplinkTeam membership information for a user.

my-membership


api.loadConcept('my-membership');

Status 200

[
    {
        "id": 53,
        "joined": "2015-11-17 04:15:14",
        "role": "admin",
        "hours": 0,
        "team": "/team/104",
        "issuer": "/brand/104",
        "@type": "userMembership",
        "@id": "/user/21/memberships?member_id=53",
        "edit": "/form/member-edit",
        "revoke": "/form/member-revoke"
    }
]

The current user's membership information. A user may belong to one or more brands.

PropertyTypeDescription
@idstring...
@typestring...
hoursintegerThe number of hours per week that a member spends towards contributing to the team goals.
idintegerA numeric identifier for a resource, that is unique for a given resource type.
joinedstringThe date when a user joined a team.
rolestringA user's role within the given context, such as a team member role or a payment role.
Links
issuerlinkWhen given as part of a resource, this links to an admin view of the related brand resource.
teamlinkWhen given as part of a resource, this links to a member view of the related brand resource.
Forms
acceptformA form for accepting an offer, such as a membership offer where acceptance is indicated by the 'joined' date.
editformA form for updating a resource.
revokeformA form for revoking a current relation between resources, such as user membership in a team.

my-membership-accept


api.loadId(currResource['accept']).then(...);

Status 200

// the response returned by promise.then
{
    "title": "Accept membership",
    "@type": "form",
    "@id": "/form/member-accept",
    "method": "POST",
    "inputs": {
        "required": [
            "joined"
        ],
        "optional": [

        ]
    }
}

Accept membership

PropertyValue
methodPOST
inputs required["joined"]
inputs optional[]

my-membership-accept-0

var currResource = {
    "@id": "/user/21/memberships?member_id=53"
};

api.submit(currResource, 'accept', {
    "joined": "{date}"
}, successFxn, errorFxn);

Example: should allow a member to accept membership by providing a joined date

Status 200

{
    "joined": "2016-01-21 00:00:00"
}

my-membership-revoke


api.loadId(currResource['revoke']).then(...);

Status 200

// the response returned by promise.then
{
    "title": "Revoke Membership",
    "@type": "form",
    "@id": "/form/member-revoke",
    "method": "POST",
    "inputs": {
        "required": [
            "revoked"
        ],
        "optional": [

        ]
    }
}

Revoke Membership

PropertyValue
methodPOST
inputs required["revoked"]
inputs optional[]

my-team


api.loadConcept('my-team');

Status 200

{
    "id": 104,
    "name": "abc",
    "logo": null,
    "@id": "/team/104",
    "@type": "brand",
    "members": "/team/104/members",
    "accounts": "/team/104/accounts",
    "throttles": "/team/104/throttles",
    "records": "/budget/104/records",
    "about": "/brand/104/about",
    "promos": "/brand/104/promos",
    "tally": "/brand/104/tally",
    "edit": "/form/brand-edit",
    "orders": "/team/104/orders"
}

blah blah blah

PropertyTypeDescription
@idstring...
@typestring...
idintegerA numeric identifier for a resource, that is unique for a given resource type.
logoNULLAn external link to an icon image that symbolizes a brand.
namestringThe name of the resource.
Links
aboutlinkInformation about the current resource.
accountslinkA collection of brand accounts, that is, a brand's ledger.
memberslinkA collection of brand members.
orderslink...
promoslinkA collection of brand promotions.
recordslinkA collection of 'record'.
tallylinkPeriodic aggregated budget activity information, by brand and type of activity.
throttleslinkA collection of 'throttle'.
Forms
editformA form for updating a resource.

my-issuer


api.loadConcept('my-issuer');

Status 200

{
    "id": 104,
    "@type": "brand",
    "@id": "/brand/104",
    "role": "admin",
    "name": "abc",
    "brand_name": "abc",
    "members": "/brand/104/members",
    "accounts": "/brand/104/accounts",
    "about": "/brand/104/about",
    "promos": "/brand/104/promos",
    "records": "/budget/104/records",
    "throttles": "/budget/104/throttles",
    "tally": "/brand/104/tally",
    "edit": "/form/brand-edit"
}

blah blah blah

PropertyTypeDescription
@idstring...
@typestring...
brand_namestring(deprecated) The name of the related brand. Use the (sub)resource 'name' instead.
idintegerA numeric identifier for a resource, that is unique for a given resource type.
namestringThe name of the resource.
rolestringA user's role within the given context, such as a team member role or a payment role.
Links
aboutlinkInformation about the current resource.
accountslinkA collection of brand accounts, that is, a brand's ledger.
memberslinkA collection of brand members.
promoslinkA collection of brand promotions.
recordslinkA collection of 'record'.
tallylinkPeriodic aggregated budget activity information, by brand and type of activity.
throttleslinkA collection of 'throttle'.
Forms
editformA form for updating a resource.

my-holdings


api.loadConcept('my-holdings');

Status 200

{
    "@type": "userAccounts",
    "user_id": 21,
    "@id": "/user/21/accounts",
    "collectionOf": "holding",
    "edit": "/form/holder-edit",
    "holding": [
        "/user/21/accounts?holder_id=41",
        "/user/21/accounts?holder_id=42",
        "/user/21/accounts?holder_id=43"
    ]
}

The current user's collection of accountholdings.

PropertyTypeDescription
@idstring...
@typestring...
collectionOfstringThe term used for the collection item. For example, instead of promos.items, you could use promos.promo or promos[promos.collectionOf].
user_idinteger(deprecated)
Links
holdinglinkAn accountholding.
Forms
editformA form for updating a resource.

my-holding


api.loadConcept('my-holding');

Status 200

[
    {
        "id": 41,
        "alias": "Main Revenue",
        "limkey": "abc",
        "authcode": "cftix",
        "account": "/account/92",
        "user": "/user/21",
        "relay": [

        ],
        "@type": "userAccount",
        "@id": "/user/21/accounts?holder_id=41",
        "relayDefault": {
            "token": "41-abc",
            "for": [
                "transfer",
                "use"
            ]
        },
        "add": "/form/budget-add",
        "transfer": "/form/budget-transfer",
        "edit": "/form/holder-edit",
        "relays": "/holder/41/relays"
    }
]

The current user's accountholdings.

PropertyTypeDescription
@idstring...
@typestring...
aliasstringAn alternate name for a resource. For example, an accountholder may assign an alias to the holding instead of referring to it by the account name.
authcodestringThe permissions related to a resource. In the case of an account or an accountholding, the authcode encodes which transaction activities are allowed based on the intersecting values between account.authcode and holder.authcode. The presence of the following characters in the authcode signify the corresponding permission: 'c' to add budget, 'f' to act as a budget transfer originator, 't' to act as a buget transfer recipient, 'i' for internal budget use within a brand, 'x' for external budget use between brands.
idintegerA numeric identifier for a resource, that is unique for a given resource type.
limkeystringShort for 'limited key', this is a semi-secret string that an accountholder shares as part of the relayDefault token to pre-authorize a payment. The token is usually in the format 'holder.id-limkey'. This token should be used only with trusted cotransactors and should not be published. For published relays such as used in promo advertisements, see the 'my-relay' resource.
relayDefaultobjectThe default relay associated with an accountholding; it does not require a user to create it but is instead based off the 'limkey' value.
userstringA person-resource.
Links
accountlinkA brand account. An account with a sign=-1 is a revenue budget that holds debits, with a normal balance of <= 0, to be used for receiving payments. An account with a sign=1 is an expense budget that holds credits, with a normal balance >=0, to be used as payment.
relaylinkA token that is used to preauthorize the use of a recipient account.
relayslinkA collection of relay tokens.
Forms
addformA form for adding a resource to a collection, or for adding to a resource's tracked quantity.
editformA form for updating a resource.
transferformA form for transferring a resource between collections, or for transferring tracked quantities between resources.
useformA form for using a resource or its tracked quantity.

my-holding-edit


api.loadId(currResource['edit']).then(...);

Status 200

// the response returned by promise.then
{
    "title": "Edit",
    "@type": "form",
    "@id": "/form/holder-edit",
    "method": "POST",
    "inputs": {
        "required": [

        ],
        "optional": [
            "alias",
            "limkey"
        ]
    }
}

Edit

PropertyValue
methodPOST
inputs required[]
inputs optional["alias","limkey"]

my-holding-edit-0

var currResource = {
    "@id": "/user/21/accounts?holder_id=41"
};

api.submit(currResource, 'edit', {
    "alias": "nickname-{xtime}"
}, successFxn, errorFxn);

Example: should allow a holder to edit the accountholding's alias

Status 200

{
    "alias": "nickname-1453363549"
}

my-holding-edit-1

var currResource = {
    "@id": "/user/21/accounts?holder_id=44"
};

api.submit(currResource, 'edit', {
    "alias": "nickname-{xtime}"
}, successFxn, errorFxn);

Example: should NOT allow a non-holder to edit an account's alias

Status 403

{
    "@context": "/api/ref/context.php",
    "error": "The requester cannot set another holder's information. \n\t\t\t\tPlease check that requester (#21) is filtering by his or her own holder_id (#44).",
    "hints": [

    ],
    "@graph": [

    ],
    "requestURI": "/user/21/accounts?holder_id=44"
}

my-holding-add


api.loadId(currResource['add']).then(...);

Status 200

// the response returned by promise.then
{
    "title": "Issue budget",
    "@type": "form",
    "@id": "/form/budget-add",
    "method": "POST",
    "target": "/budget/issued",
    "query": {
        "required": [
            "account-brand-id"
        ],
        "optional": [

        ]
    },
    "inputs": {
        "required": [
            "from",
            "to",
            "amount",
            "note"
        ],
        "optional": [

        ]
    }
}

Issue budget

PropertyValue
methodPOST
inputs required["from","to","amount","note"]
inputs optional[]

my-holding-add-0

var currResource = {
    "account": {
        "brand": {
            "id": 104
        }
    }
};

api.submit(currResource, 'add', {
    "from": "41-abc",
    "to": "42-abc",
    "amount": 200,
    "note": "test budget issuance"
}, successFxn, errorFxn);

Example: should allow an accountholding with a 'c' authcode to issue budget

Status 200

{
    "@type": "budgetIssued",
    "brand_id": 104,
    "@id": "/budgets/104/issued",
    "amount": 200,
    "note": "test budget issuance",
    "from_acct": 92,
    "from_user": 21,
    "txntype": "np",
    "record_id": 38,
    "status": 7
}

my-holding-add-1

var currResource = {
    "account": {
        "brand": {
            "id": 104
        }
    }
};

api.submit(currResource, 'add', {
    "from": "41-abc",
    "to": "43-abc",
    "amount": 200,
    "note": "test budget issuance"
}, successFxn, errorFxn);

Example: should NOT allow an accountholding without a 'c' authcode to issue budget

Status 403

{
    "@context": "/api/ref/context.php",
    "error": " The to-account #94 is not authorized for budget creation. The to-acct-holder is not authorized to create budgets using account #94.",
    "hints": [

    ],
    "@graph": [

    ],
    "requestURI": "/budget/issued?account-brand-id=104"
}

my-holding-transfer


api.loadId(currResource['transfer']).then(...);

Status 200

// the response returned by promise.then
{
    "title": "Transfer budget",
    "@type": "form",
    "@id": "/form/budget-transfer",
    "method": "POST",
    "target": "/budget/transferred",
    "query": {
        "required": [
            "account-brand-id"
        ],
        "optional": [

        ]
    },
    "inputs": {
        "required": [
            "from",
            "to",
            "amount",
            "note"
        ],
        "optional": [

        ]
    }
}

Transfer budget

PropertyValue
methodPOST
inputs required["from","to","amount","note"]
inputs optional[]

my-holding-transfer-0

var currResource = {
    "account": {
        "brand": {
            "id": 104
        }
    }
};

api.submit(currResource, 'transfer', {
    "from": "42-abc",
    "to": "43-abc",
    "amount": 22,
    "note": "test budget transfer"
}, successFxn, errorFxn);

Example: should allow an originating accountholding with an 'f' and destination accountholding with a 't' authcode to transfer budgets.

Status 200

{
    "@type": "budgetTransferred",
    "brand_id": 104,
    "@id": "/budgets/104/transferred",
    "amount": 22,
    "note": "test budget transfer",
    "from_acct": 93,
    "from_user": 21,
    "txntype": "pp",
    "record_id": 39,
    "status": 7
}

my-holding-use


api.loadId(currResource['use']).then(...);

Status 200

// the response returned by promise.then
{
    "title": "Use budget",
    "@type": "form",
    "@id": "/form/budget-use",
    "method": "POST",
    "target": "/budget/used",
    "query": {
        "required": [
            "account-brand-id"
        ],
        "optional": [

        ]
    },
    "inputs": {
        "required": [
            "from",
            "to",
            "amount",
            "note"
        ],
        "optional": [

        ]
    }
}

Use budget

PropertyValue
methodPOST
inputs required["from","to","amount","note"]
inputs optional[]

my-holding-use-0

var currResource = {
    "account": {
        "brand": {
            "id": 104
        }
    }
};

api.submit(currResource, 'use', {
    "from": "42-abc",
    "to": "44-abc",
    "amount": 11.11,
    "note": "test budget use"
}, successFxn, errorFxn);

Example: should allow an accountholding with an 'x' to use budgets.

Status 200

{
    "@type": "budgetUsed",
    "brand_id": 104,
    "@id": "/budgets/104/used",
    "amount": 11.11,
    "note": "test budget use",
    "from_acct": 93,
    "from_user": 21,
    "txntype": "pn",
    "throttle_id": 0,
    "relay_id": 0,
    "promo_id": 0,
    "record_id": 40
}

my-holding-use-1

var currResource = {
    "account": {
        "brand": {
            "id": 104
        }
    }
};

api.submit(currResource, 'use', {
    "from": "42-abc",
    "to": "3.xyz",
    "amount": 1.11,
    "note": "test budget use"
}, successFxn, errorFxn);

Example: should allow the use of a valid relay credential to authorize a transaction.

Status 200

{
    "@type": "budgetUsed",
    "brand_id": 104,
    "@id": "/budgets/104/used",
    "amount": 1.11,
    "note": "test budget use",
    "from_acct": 93,
    "from_user": 21,
    "txntype": "pn",
    "throttle_id": 0,
    "relay_id": 3,
    "promo_id": 0,
    "record_id": 41
}

my-holding-use-2

var currResource = {
    "account": {
        "brand": {
            "id": 104
        }
    }
};

api.submit(currResource, 'use', {
    "from": "42-abc",
    "to": "3.xyz",
    "amount": 51.11,
    "note": "test budget use"
}, successFxn, errorFxn);

Example: should void the transaction when the transaction amount is not within a relay's amount_min and _max

Status 403

{
    "@context": "/api/ref/context.php",
    "error": "The amount must be between 0.01 and 50.00.",
    "hints": [

    ],
    "@graph": [

    ],
    "requestURI": "/budget/used?account-brand-id=104"
}

my-holding-use-3

var currResource = {
    "account": {
        "brand": {
            "id": 104
        }
    }
};

api.submit(currResource, 'use', {
    "from": "42-abc",
    "to": "3.xyz",
    "note": "test budget use"
}, successFxn, errorFxn);

Example: should fill-in missing transaction amount

Status 200

{
    "@type": "budgetUsed",
    "brand_id": 104,
    "@id": "/budgets/104/used",
    "note": "test budget use",
    "from_acct": 93,
    "from_user": 21,
    "amount": 0.01,
    "txntype": "pn",
    "throttle_id": 0,
    "relay_id": 3,
    "promo_id": 0,
    "record_id": 42
}

my-holding-use-4

var currResource = {
    "account": {
        "brand": {
            "id": 104
        }
    }
};

api.submit(currResource, 'use', {
    "from": "42-abc",
    "to": "4.qrs",
    "amount": 0.12,
    "note": "test budget use"
}, successFxn, errorFxn);

Example: should not allow relay usage that exceeds limits

Status 403

{
    "@context": "/api/ref/context.php",
    "error": "The user relay usage limit of 0 within the last seven days has been reached or exceeded (counted 0 uses).",
    "hints": [

    ],
    "@graph": [

    ],
    "requestURI": "/budget/used?account-brand-id=104"
}

my-holding-use-5

var currResource = {
    "account": {
        "brand": {
            "id": 104
        }
    }
};

api.submit(currResource, 'use', {
    "from": "42-abc",
    "to": "ad-1",
    "note": "test budget use"
}, successFxn, errorFxn);

Example: should convert promo to correct record info

Status 200

{
    "@type": "budgetUsed",
    "brand_id": 104,
    "@id": "/budgets/104/used",
    "note": "test budget use",
    "from_acct": 93,
    "from_user": 21,
    "amount": 25,
    "txntype": "pn",
    "throttle_id": 0,
    "relay_id": 1,
    "promo_id": 1,
    "record_id": 43
}

my-account


api.loadConcept('my-account');

Status 200

{
    "id": 92,
    "name": "Main Revenue",
    "sign": -1,
    "balance": 1399.98,
    "unit": "hour",
    "authcode": "cftix",
    "@id": "/account/92",
    "@type": "account",
    "records": "/account/92/records",
    "brand": "/team/104",
    "throttle": "/throttle/0"
}

The account referenced in an accountholding.

PropertyTypeDescription
@idstring...
@typestring...
authcodestringThe permissions related to a resource. In the case of an account or an accountholding, the authcode encodes which transaction activities are allowed based on the intersecting values between account.authcode and holder.authcode. The presence of the following characters in the authcode signify the corresponding permission: 'c' to add budget, 'f' to act as a budget transfer originator, 't' to act as a buget transfer recipient, 'i' for internal budget use within a brand, 'x' for external budget use between brands.
balancedoubleThe available amount related to a resource, such as an account balance.
idintegerA numeric identifier for a resource, that is unique for a given resource type.
namestringThe name of the resource.
signintegerIndicates whether an account is a revenue (-1) or expense (+1) budget.
unitstringThe accounting-unit of a budget, also the currency unit. The only possible value right now is XTE.
Links
brandlinkThe currency issuer related to this resource.
recordslinkA collection of 'record'.
throttlelinkA limit on how much an account may be used for transactions for a given period, specified as amount per brand, amount per user, and amount by all.

my-account-records


api.loadConcept('my-account-records');

Status 200

{
    "pageOrder": "desc",
    "itemsLimit": 50,
    "collectionOf": "record",
    "pageOf": "/account/92/records",
    "account_id": 92,
    "brand_id": 104,
    "holder_id": 41,
    "limkey": "abc",
    "@type": "accountRecords",
    "@id": "/account/92/records",
    "record": [
        "/account/92/records?record_id=64",
        "/account/92/records?record_id=63",
        "/account/92/records?record_id=62"
    ],
    "hold": "/form/record-hold",
    "approve": "/form/record-approve",
    "reject": "/form/record-reject"
}

A collection of account transaction records, most recent first.

PropertyTypeDescription
@idstring...
@typestring...
account_idinteger...
brand_idinteger(deprecated)
collectionOfstringThe term used for the collection item. For example, instead of promos.items, you could use promos.promo or promos[promos.collectionOf].
holder_idinteger...
itemsLimitintegerThe maximum number of items that is returned in a collection page. To request more than the itemsLimit, make subsequent requests using the collection's 'next' or 'prev' link.
limkeystringShort for 'limited key', this is a semi-secret string that an accountholder shares as part of the relayDefault token to pre-authorize a payment. The token is usually in the format 'holder.id-limkey'. This token should be used only with trusted cotransactors and should not be published. For published relays such as used in promo advertisements, see the 'my-relay' resource.
pageOfstringThe '@id' of the collection to which the current page belongs. In other words, this is the link to the default collection resource without pagination.
pageOrderstringEither 'asc' or 'desc' based on item id's.
Links
recordlinkTracked information about a resource, usually involving lifecycle events, such as a transaction record.
Forms
approveformA form for approving the completion of a pending resource action.
holdformA form for preventing the auto-approval or auto-rejection of a pending resource action.
rejectformA form for rejecting the completion of a pending resource action.

my-account-record


api.loadConcept('my-account-record');

Status 200

[
    {
        "record_id": 64,
        "txntype": "pn",
        "role": "from",
        "throttle_id": 0,
        "other_acct": 94,
        "brand_id": 104,
        "brand_name": "abc",
        "amount": -1.11,
        "created": "2015-11-21 14:10:38",
        "status": 7,
        "note": "",
        "updated": 1448144507,
        "@type": "accountRecord",
        "@id": "/account/92/records?record_id=64",
        "id": 64,
        "other": 94
    }
]

An account's transaction record.

PropertyTypeDescription
@idstring...
@typestring...
amountdoubleA numeric value that quantifies an important aspect of a resource. For example, in the context of a promo or transaction record, the amount may be a product price or a suggested donation amount.
brand_idinteger(deprecated)
brand_namestring(deprecated) The name of the related brand. Use the (sub)resource 'name' instead.
createdstringThe date and time when a resource was created, in the form of `YYYY-MM-DD hh:mm:ss`.
idintegerA numeric identifier for a resource, that is unique for a given resource type.
notestringA short text used to annotate a resource such as a transaction record.
otherintegerThe other brand in a transaction record, from the viewpoint of an accountholder.
other_acctintegerThe other account in a transaction record, from the viewpoint of an accountholder.
record_idinteger(deprecated)
rolestringA user's role within the given context, such as a team member role or a payment role.
statusintegerAn integer associated with the current state of a resource. For example, a transaction record may be pending automated approval (status=0), on hold for manual approval (status=5), approved (status=7), or rejected (status <0).
throttle_idinteger(deprecated)
txntypestringThe type of budget activity that a transaction record is classified as. There are four possible values: 'np' (budget add), 'nn' (revenue budget transfer), 'pp' (expense budget transfer), and 'pn' (budget use).
updatedintegerThe UNIX timestamp when a resource was last updated.
Forms
approveformA form for approving the completion of a pending resource action.
holdformA form for preventing the auto-approval or auto-rejection of a pending resource action.
rejectformA form for rejecting the completion of a pending resource action.
unaddformA form for reversing a previous approved 'add' action.
unuseformA form for reversing a previously approved 'use' action.

my-account-record-hold


api.loadId(currResource['hold']).then(...);

Status 200

// the response returned by promise.then
{
    "title": "Hold transaction (disable auto-approval)",
    "@type": "form",
    "@id": "/form/record-hold",
    "method": "POST",
    "inputs": {
        "required": [
            "status"
        ],
        "optional": [

        ],
        "valueRestrictions": {
            "status": [
                5
            ]
        }
    }
}

Hold transaction (disable auto-approval)

PropertyValue
methodPOST
inputs required["status"]
inputs optional[]

my-account-record-hold-0

var currResource = {
    "@id": "/account/92/records?record_id=30"
};

api.submit(currResource, 'hold', {
    "status": 5
}, successFxn, errorFxn);

Example: should allow putting record on hold

Status 200

{
    "status": 5
}

my-account-record-approve


api.loadId(currResource['approve']).then(...);

Status 200

// the response returned by promise.then
{
    "title": "Manually approve transaction",
    "@type": "form",
    "@id": "/form/record-approve",
    "method": "POST",
    "inputs": {
        "required": [
            "status"
        ],
        "optional": [

        ],
        "valueRestrictions": {
            "status": [
                7
            ]
        }
    }
}

Manually approve transaction

PropertyValue
methodPOST
inputs required["status"]
inputs optional[]

my-account-record-approve-0

var currResource = {
    "@id": "/account/92/records?record_id=30"
};

api.submit(currResource, 'approve', {
    "status": 7
}, successFxn, errorFxn);

Example: should allow record approval

Status 200

{
    "status": 7
}

my-account-record-reject


api.loadId(currResource['reject']).then(...);

Status 200

// the response returned by promise.then
{
    "title": "Manually reject transaction",
    "@type": "form",
    "@id": "/form/record-reject",
    "method": "POST",
    "inputs": {
        "required": [
            "status"
        ],
        "optional": [

        ],
        "valueRestrictions": {
            "status": [
                -10
            ]
        }
    }
}

Manually reject transaction

PropertyValue
methodPOST
inputs required["status"]
inputs optional[]

my-account-record-reject-0

var currResource = {
    "@id": "/account/92/records?record_id=30"
};

api.submit(currResource, 'reject', {
    "status": -10
}, successFxn, errorFxn);

Example: should allow record rejection

Status 200

{
    "status": -10
}

my-account-record-unuse


api.loadId(currResource['unuse']).then(...);

Status 200

// the response returned by promise.then
{
    "title": "Reverse used budget",
    "@type": "form",
    "@id": "/form/budget-unuse",
    "method": "POST",
    "target": "/budget/used",
    "query": {
        "required": [
            "account-brand-id"
        ],
        "optional": [

        ]
    },
    "inputs": {
        "required": [
            "from",
            "to",
            "amount",
            "note",
            "orig_record_id"
        ],
        "optional": [

        ]
    }
}

Reverse used budget

PropertyValue
methodPOST
inputs required["from","to","amount","note","orig_record_id"]
inputs optional[]

my-account-record-unuse-0

var currResource = {
    "account": {
        "brand": {
            "id": 104
        }
    }
};

api.submit(currResource, 'unuse', {
    "from": "45-abc",
    "to": "41-abc",
    "amount": -1.01,
    "note": "test used budget reversal",
    "orig_record_id": 34
}, successFxn, errorFxn);

Example: should allow reversal of used budget

Status 200

{
    "@type": "budgetUsed",
    "brand_id": 104,
    "@id": "/budgets/104/used",
    "amount": -1.01,
    "note": "test used budget reversal",
    "from_acct": 96,
    "from_user": 22,
    "txntype": "pn",
    "throttle_id": 0,
    "relay_id": 0,
    "promo_id": 0,
    "record_id": 44,
    "reversal_id": 0
}

my-relays


api.loadConcept('my-relays');

Status 200

{
    "pageOrder": "desc",
    "itemsLimit": 50,
    "collectionOf": "relay",
    "pageOf": "/holder/41/relays",
    "holder_id": 41,
    "@type": "holderRelays",
    "@id": "/holder/41/relays",
    "relay": [
        {
            "id": 1,
            "holder_id": 41,
            "user_id": 21,
            "account_id": 92,
            "amount_min": 0.01,
            "amount_max": 100,
            "redirect": null,
            "secret": null,
            "tag": "test",
            "txntype": "pn",
            "created": "2014-12-31 16:00:00",
            "updated": null,
            "by_all_limit": 25,
            "by_brand_limit": 5,
            "by_user_limit": 25,
            "by_user_wait": 24,
            "token": 1,
            "@id": "/relay/1",
            "@type": "relay",
            "edit": "/form/relay-edit"
        },
        {
            "id": 2,
            "holder_id": 41,
            "user_id": 21,
            "account_id": 92,
            "amount_min": 5,
            "amount_max": 10,
            "redirect": null,
            "secret": null,
            "tag": "test",
            "txntype": "pn",
            "created": "2014-12-31 16:00:00",
            "updated": null,
            "by_all_limit": 25,
            "by_brand_limit": 5,
            "by_user_limit": 25,
            "by_user_wait": 0,
            "token": 2,
            "@id": "/relay/2",
            "@type": "relay",
            "edit": "/form/relay-edit"
        },
        {
            "id": 5,
            "holder_id": 41,
            "user_id": 21,
            "account_id": 92,
            "amount_min": 57.57,
            "amount_max": 57.57,
            "redirect": null,
            "secret": "7d02",
            "tag": null,
            "txntype": "pn",
            "created": "2015-11-17 16:15:57",
            "updated": null,
            "by_all_limit": 25,
            "by_brand_limit": 5,
            "by_user_limit": 2,
            "by_user_wait": 24,
            "token": "5.7d02",
            "@id": "/relay/5",
            "@type": "relay",
            "edit": "/form/relay-edit"
        }
    ],
    "add": "/form/holder-relays-add"
}

blah blah blah

PropertyTypeDescription
@idstring...
@typestring...
collectionOfstringThe term used for the collection item. For example, instead of promos.items, you could use promos.promo or promos[promos.collectionOf].
holder_idinteger...
itemsLimitintegerThe maximum number of items that is returned in a collection page. To request more than the itemsLimit, make subsequent requests using the collection's 'next' or 'prev' link.
pageOfstringThe '@id' of the collection to which the current page belongs. In other words, this is the link to the default collection resource without pagination.
pageOrderstringEither 'asc' or 'desc' based on item id's.
Links
relaylinkA token that is used to preauthorize the use of a recipient account.
Forms
addformA form for adding a resource to a collection, or for adding to a resource's tracked quantity.

my-relays-add


api.loadId(currResource['add']).then(...);

Status 200

// the response returned by promise.then
{
    "title": "Add",
    "@type": "form",
    "@id": "/form/holder-relays-add",
    "method": "POST",
    "inputs": {
        "required": [

        ],
        "optional": [
            "amount_min",
            "amount_max",
            "redirect",
            "tag",
            "secret",
            "txntype",
            "ended",
            "by_all_limit",
            "by_brand_limit",
            "by_user_limit",
            "by_user_wait"
        ]
    }
}

Add

PropertyValue
methodPOST
inputs required[]
inputs optional["amount_min","amount_max","redirect","tag","secret","txntype","ended","by_all_limit","by_brand_limit","by_user_limit","by_user_wait"]

my-relays-add-0

var currResource = {
    "@id": "/holder/41/relays"
};

api.submit(currResource, 'add', {
    "amount_min": 0,
    "amount_max": "{random}"
}, successFxn, errorFxn);

Example: should allow an accountholder to add a relay specification

Status 200

{
    "amount_min": 0,
    "amount_max": 155,
    "relay_id": 5
}

my-relays-add-1

var currResource = {
    "@id": "/holder/44/relays"
};

api.submit(currResource, 'add', {
    "amount_min": 0,
    "amount_max": "{random}"
}, successFxn, errorFxn);

Example: should NOT allow a non-accountholder to add a relay specification

Status 403

{
    "@context": "/api/ref/context.php",
    "error": "The user does not have access to this accountholder's information.",
    "hints": [

    ],
    "@graph": [

    ],
    "requestURI": "/holder/44/relays"
}

my-relay


api.loadConcept('my-relay');

Status 200

[
    {
        "id": 1,
        "holder_id": 41,
        "user_id": 21,
        "account_id": 92,
        "amount_min": 0.01,
        "amount_max": 100,
        "redirect": null,
        "secret": null,
        "tag": "test",
        "txntype": "pn",
        "created": "2014-12-31 16:00:00",
        "updated": null,
        "by_all_limit": 25,
        "by_brand_limit": 5,
        "by_user_limit": 25,
        "by_user_wait": 24,
        "token": 1,
        "@id": "/relay/1",
        "@type": "relay",
        "edit": "/form/relay-edit"
    }
]

blah blah blah

PropertyTypeDescription
@idstring...
@typestring...
account_idinteger...
amount_maxinteger...
amount_mindouble...
by_all_limitintegerThis is a weekly limit on the total inflow transaction amount for a given account or usage for a given product, regardless of the payor's brand or user id. This is similar to coupon restrictions, allowing your brand to set limits on transactions and also to combat spammy payment offers.
by_brand_limitintegerA weekly limit on total inflow transaction amount for a given account or usage for a given promo, based on the payor's brand id. This is similar to coupon restrictions, allowing your brand to set limits on transactions and also to combat spammy payment offers.
by_user_limitintegerA weekly limit on total inflow transaction amount for a given account or usage for a given promo, based on the payor's user id. This is similar to coupon restrictions, allowing your brand to set limits on transactions and also to combat spammy payment offers.
by_user_waitintegerHow long a user must wait after using a promo, before that user can reuse the same promo.
createdstringThe date and time when a resource was created, in the form of `YYYY-MM-DD hh:mm:ss`.
holder_idinteger...
idintegerA numeric identifier for a resource, that is unique for a given resource type.
redirectNULL...
secretNULL...
tagstring...
tokeninteger...
txntypestringThe type of budget activity that a transaction record is classified as. There are four possible values: 'np' (budget add), 'nn' (revenue budget transfer), 'pp' (expense budget transfer), and 'pn' (budget use).
updatedNULLThe UNIX timestamp when a resource was last updated.
user_idinteger(deprecated)
Forms
editformA form for updating a resource.

my-relay-edit


api.loadId(currResource['edit']).then(...);

Status 200

// the response returned by promise.then
{
    "title": "Edit",
    "@type": "form",
    "@id": "/form/relay-edit",
    "method": "POST",
    "inputs": {
        "required": [

        ],
        "optional": [
            "amount_min",
            "amount_max",
            "redirect",
            "tag",
            "secret",
            "txntype",
            "ended",
            "by_all_limit",
            "by_brand_limit",
            "by_user_limit",
            "by_user_wait"
        ]
    }
}

Edit

PropertyValue
methodPOST
inputs required[]
inputs optional["amount_min","amount_max","redirect","tag","secret","txntype","ended","by_all_limit","by_brand_limit","by_user_limit","by_user_wait"]

my-relay-edit-0

var currResource = {
    "@id": "/relay/1"
};

api.submit(currResource, 'edit', {
    "secret": "{hex}",
    "amount_max": "{random}"
}, successFxn, errorFxn);

Example: should allow an accountholder to edit a relay specification

Status 200

{
    "secret": "{hex}",
    "amount_max": 452
}

my-relay-edit-1

var currResource = {
    "@id": "/relay/3"
};

api.submit(currResource, 'edit', {
    "secret": "{hex}",
    "amount_max": "{random}"
}, successFxn, errorFxn);

Example: should NOT allow a non-accountholder to edit a relay specification

Status 403

{
    "@context": "/api/ref/context.php",
    "error": "The user does not have access to this accountholder's information.",
    "hints": [

    ],
    "@graph": [

    ],
    "requestURI": "/relay/3"
}

my-ratings


api.loadConcept('my-ratings');

Status 200

{
    "pageOrder": "desc",
    "itemsLimit": 50,
    "collectionOf": "rating",
    "pageOf": "/user/21/ratings",
    "user_id": 21,
    "@type": "userRatings",
    "@id": "/user/21/ratings",
    "add": "/form/rating-add",
    "rating": [
        {
            "rating_id": 11,
            "brand_id": 116,
            "brand_name": "~Pizza Hut, Washington 99, Edmonds, WA, United States",
            "score": 64,
            "reason": "--social responsibility",
            "created": "2015-11-18 20:21:32",
            "ended": null,
            "@id": "/user/21/ratings?rating_id=11",
            "edit": "/form/rating-edit"
        },
        {
            "rating_id": 10,
            "brand_id": 115,
            "brand_name": "~Echo Lake Elementary School, Seattle, WA, United States",
            "score": 100,
            "reason": "++good school;",
            "created": "2015-11-18 10:50:05",
            "ended": null,
            "@id": "/user/21/ratings?rating_id=10",
            "edit": "/form/rating-edit"
        },
        {
            "rating_id": 9,
            "brand_id": 114,
            "brand_name": "~P-Patch, Lynn Street, Seattle, WA, United States",
            "score": 100,
            "reason": "++environmental impact; ++community health",
            "created": "2015-08-08 18:53:23",
            "ended": null,
            "@id": "/user/21/ratings?rating_id=9",
            "edit": "/form/rating-edit"
        }
    ],
    "edit": "/form/rating-edit"
}

A collection of my-rating.

PropertyTypeDescription
@idstring...
@typestring...
collectionOfstringThe term used for the collection item. For example, instead of promos.items, you could use promos.promo or promos[promos.collectionOf].
itemsLimitintegerThe maximum number of items that is returned in a collection page. To request more than the itemsLimit, make subsequent requests using the collection's 'next' or 'prev' link.
pageOfstringThe '@id' of the collection to which the current page belongs. In other words, this is the link to the default collection resource without pagination.
pageOrderstringEither 'asc' or 'desc' based on item id's.
user_idinteger(deprecated)
Links
ratinglinkA value assigned by a user to a team or brand, recorded as a score and reason.
Forms
addformA form for adding a resource to a collection, or for adding to a resource's tracked quantity.
editformA form for updating a resource.

my-ratings-add


api.loadId(currResource['add']).then(...);

Status 200

// the response returned by promise.then
{
    "title": "Add a rating",
    "@type": "form",
    "@id": "/form/rating-add",
    "method": "POST",
    "inputs": {
        "required": [
            "brand_id",
            "score",
            "reason"
        ],
        "optional": [

        ]
    }
}

Add a rating

PropertyValue
methodPOST
inputs required["brand_id","score","reason"]
inputs optional[]

my-ratings-add-0

var currResource = {
    "@id": "/user/21/ratings"
};

api.submit(currResource, 'add', {
    "brand_id": 105,
    "score": 0,
    "reason": "polluter"
}, successFxn, errorFxn);

Example: should allow a user to add a new rating

Status 200

{
    "items": [

    ],
    "pageOrder": "desc",
    "itemsLimit": 50,
    "collectionOf": "rating",
    "pageOf": null,
    "user_id": 21,
    "@type": "userRatings",
    "@id": "/user/21/ratings",
    "score": 0,
    "reason": "polluter"
}

my-ratings-add-1

var currResource = {
    "@id": "/user/21/ratings"
};

api.submit(currResource, 'add', {
    "brand_id": "test test test {random}",
    "score": 0,
    "reason": "polluter"
}, successFxn, errorFxn);

Example: should allow a user to add a new rating for a previously unregistered brand

Status 200

{
    "items": [

    ],
    "pageOrder": "desc",
    "itemsLimit": 50,
    "collectionOf": "rating",
    "pageOf": null,
    "user_id": 21,
    "@type": "userRatings",
    "@id": "/user/21/ratings",
    "brand_id": 116,
    "score": 0,
    "reason": "polluter",
    "rating_id": 11
}

my-ratings-add-2

var currResource = {
    "@id": "/user/21/ratings"
};

api.submit(currResource, 'add', {
    "brand_id": 105,
    "score": 0,
    "reason": "polluter"
}, successFxn, errorFxn);

Example: should not allow a user to duplicate an existing rating, by other_id

Status 200

{
    "items": [

    ],
    "pageOrder": "desc",
    "itemsLimit": 50,
    "collectionOf": "rating",
    "pageOf": null,
    "user_id": 21,
    "@type": "userRatings",
    "@id": "/user/21/ratings",
    "brand_id": 105,
    "score": 0,
    "reason": "polluter",
    "rating_id": 10
}

my-rating


api.loadConcept('my-rating');

Status 200

[
    {
        "rating_id": 11,
        "brand_id": 116,
        "brand_name": "~Pizza Hut, Washington 99, Edmonds, WA, United States",
        "score": 64,
        "reason": "--social responsibility",
        "created": "2015-11-18 20:21:32",
        "ended": null,
        "@id": "/user/21/ratings?rating_id=11",
        "edit": "/form/rating-edit"
    }
]

The rating given to current user to brands.

PropertyTypeDescription
@idstring...
brand_idinteger(deprecated)
brand_namestring(deprecated) The name of the related brand. Use the (sub)resource 'name' instead.
createdstringThe date and time when a resource was created, in the form of `YYYY-MM-DD hh:mm:ss`.
endedNULLThe date of resource or relation deactivation, formatted as `YYYY-MM-DD hh:mm:ss`.
rating_idinteger...
reasonstringA rationale related to a resource, such as as why a brand was given a certain score in a rating.
scoreintegerA numeric value along a scale indicating low to high value. In the case a 'rating' resource, the score correlates to the reputation of a team or brand as a currency issuer.
Forms
editformA form for updating a resource.

my-rating-edit


api.loadId(currResource['edit']).then(...);

Status 200

// the response returned by promise.then
{
    "title": "Update a rating",
    "@type": "form",
    "@id": "/form/rating-edit",
    "method": "POST",
    "inputs": {
        "required": [

        ],
        "optional": [
            "score",
            "reason",
            "ended"
        ]
    }
}

Update a rating

PropertyValue
methodPOST
inputs required[]
inputs optional["score","reason","ended"]

my-rating-edit-0

var currResource = {
    "@id": "/user/21/ratings?rating_id=1"
};

api.submit(currResource, 'edit', {
    "score": 1,
    "reason": "non-polluter {random}"
}, successFxn, errorFxn);

Example: should allow a user to update a rating

Status 200

{
    "items": [

    ],
    "pageOrder": "desc",
    "itemsLimit": 50,
    "collectionOf": "rating",
    "pageOf": null,
    "user_id": 21,
    "@type": "userRatings",
    "@id": "/user/21/ratings",
    "score": 1,
    "reason": "non-polluter 186"
}

my-about


api.loadConcept('my-about');

Status 200

{
    "@id": "/user/21/about",
    "user_id": 21,
    "name": "User One",
    "created": "2015-01-05 11:53:31",
    "numMemberships": 1,
    "totalHours": 0
}

Public information about the currently logged-in user.

PropertyTypeDescription
@idstring...
createdstringThe date and time when a resource was created, in the form of `YYYY-MM-DD hh:mm:ss`.
namestringThe name of the resource.
numMembershipsintegerThe number of teams a user belongs to.
totalHoursintegerThe number of hours per week that a user plans to spend contributing to his team(s) goals.
user_idinteger(deprecated)

my-teams


api.loadConcept('my-teams');

Status 200

{
    "@type": "userTeams",
    "user_id": 21,
    "@id": "/user/21/teams",
    "collectionOf": "brand",
    "brand": [
        "/team/104"
    ]
}

A collection of the teams that the current user belongs to.

PropertyTypeDescription
@idstring...
@typestring...
collectionOfstringThe term used for the collection item. For example, instead of promos.items, you could use promos.promo or promos[promos.collectionOf].
user_idinteger(deprecated)
Links
brandlinkThe currency issuer related to this resource.

my-issuers


api.loadConcept('my-issuers');

Status 200

{
    "pageOrder": null,
    "itemsLimit": 50,
    "collectionOf": "brand",
    "pageOf": null,
    "@type": "userBrands",
    "user_id": 21,
    "@id": "/user/21/brands",
    "brand": [
        "/brand/104"
    ],
    "add": "/form/brand-registration"
}

blah blah blah

PropertyTypeDescription
@idstring...
@typestring...
collectionOfstringThe term used for the collection item. For example, instead of promos.items, you could use promos.promo or promos[promos.collectionOf].
itemsLimitintegerThe maximum number of items that is returned in a collection page. To request more than the itemsLimit, make subsequent requests using the collection's 'next' or 'prev' link.
pageOfNULLThe '@id' of the collection to which the current page belongs. In other words, this is the link to the default collection resource without pagination.
pageOrderNULLEither 'asc' or 'desc' based on item id's.
user_idinteger(deprecated)
Links
brandlinkThe currency issuer related to this resource.
Forms
addformA form for adding a resource to a collection, or for adding to a resource's tracked quantity.

my-issuers-add


api.loadId(currResource['add']).then(...);

Status 200

// the response returned by promise.then
{
    "title": "Brand registration",
    "@type": "form",
    "@id": "/form/brand-registration",
    "method": "POST",
    "inputs": {
        "required": [
            "name",
            "mission",
            "description"
        ],
        "optional": [
            "url",
            "advisor",
            "type_system",
            "type_id",
            "country_code",
            "area_code"
        ]
    }
}

Brand registration

PropertyValue
methodPOST
inputs required["name","mission","description"]
inputs optional["url","advisor","type_system","type_id","country_code","area_code"]

my-issuers-add-0

var currResource = {
    "@id": "/user/21/brands"
};

api.submit(currResource, 'add', {
    "name": "abc-{xtime}.org",
    "mission": "To be the third brand - {xtime}",
    "description": "the third brand"
}, successFxn, errorFxn);

Example: should allow registration by a brand new user

Status 200

{
    "name": "abc-1453363549.org",
    "mission": "To be the third brand - 1453363549",
    "description": "the third brand",
    "brand_id": 115,
    "members": [
        {
            "brand_id": 115,
            "user_id": 21,
            "role": "admin",
            "hours": 0,
            "member_id": 56
        }
    ],
    "accounts": [
        {
            "account_id": 116,
            "brand_id": 115,
            "name": "Main Revenue",
            "authcode": "cftix",
            "unit": "hour",
            "sign": -1
        },
        {
            "account_id": 117,
            "brand_id": 115,
            "name": "Main Expense",
            "authcode": "cftix",
            "unit": "hour",
            "sign": 1
        }
    ],
    "holders": [
        {
            "holder_id": 46,
            "account_id": 116,
            "user_id": 21,
            "authcode": "cftix",
            "limkey": "abc"
        },
        {
            "holder_id": 47,
            "account_id": 117,
            "user_id": 21,
            "authcode": "cftix",
            "limkey": "abc"
        }
    ]
}

my-issuers-add-1

var currResource = {
    "@id": "/user/21/brands"
};

api.submit(currResource, 'add', {
    "name": "xyz-{xtime}.org",
    "description": "the third brand"
}, successFxn, errorFxn);

Example: should NOT allow user registration with missing mission

Status 403

{
    "@context": "/api/ref/context.php",
    "error": "Missing object properties: mission",
    "hints": [

    ],
    "@graph": [

    ],
    "requestURI": "/user/21/brands"
}

my-apps


api.loadConcept('my-apps');

Status 200

{
    "pageOrder": "asc",
    "itemsLimit": 50,
    "collectionOf": "app",
    "pageOf": "/user/21/apps",
    "user_id": 21,
    "@id": "/user/21/apps",
    "@type": "userApps",
    "app": [
        "/app/trial",
        "/app/1/details",
        "/app/2/details"
    ],
    "add": "/form/app-add"
}

A user's collection of 'app'.

PropertyTypeDescription
@idstring...
@typestring...
collectionOfstringThe term used for the collection item. For example, instead of promos.items, you could use promos.promo or promos[promos.collectionOf].
itemsLimitintegerThe maximum number of items that is returned in a collection page. To request more than the itemsLimit, make subsequent requests using the collection's 'next' or 'prev' link.
pageOfstringThe '@id' of the collection to which the current page belongs. In other words, this is the link to the default collection resource without pagination.
pageOrderstringEither 'asc' or 'desc' based on item id's.
user_idinteger(deprecated)
Links
applink...
Forms
addformA form for adding a resource to a collection, or for adding to a resource's tracked quantity.

my-apps-add


api.loadId(currResource['add']).then(...);

Status 200

// the response returned by promise.then
{
    "title": "Add a new application",
    "@type": "form",
    "@id": "/form/app-add",
    "method": "POST",
    "inputs": {
        "required": [
            "name",
            "secret"
        ],
        "optional": [
            "redirect_url"
        ]
    }
}

Add a new application

PropertyValue
methodPOST
inputs required["name","secret"]
inputs optional["redirect_url"]

my-apps-add-0

var currResource = {
    "@id": "/user/21/apps"
};

api.submit(currResource, 'add', {
    "name": "my test app",
    "secret": "Ksi380sgtrpeOiwskswidf120m75"
}, successFxn, errorFxn);

Example: should allow a user to add an application

Status 200

{
    "name": "my test app",
    "secret": "Ksi380sgtrpeOiwskswidf120m75",
    "consumer_id": 7
}

Team Resources

All members of a team share access to these resources. The accessible resources are based on the membership of the currently logged-in user.

team-brand


api.loadConcept('team-brand');

Status 200

[
    {
        "id": 104,
        "@type": "brand",
        "@id": "/team/104",
        "name": "abc",
        "logo": null,
        "members": "/team/104/members",
        "accounts": "/team/104/accounts",
        "throttles": "/team/104/throttles",
        "records": "/budget/104/records",
        "about": "/brand/104/about",
        "promos": "/brand/104/promos",
        "orders": "/team/104/orders",
        "tally": "/brand/104/tally",
        "edit": "/form/brand-edit"
    }
]

A brand to which the current user belongs to.

PropertyTypeDescription
@idstring...
@typestring...
idintegerA numeric identifier for a resource, that is unique for a given resource type.
logoNULLAn external link to an icon image that symbolizes a brand.
namestringThe name of the resource.
Links
aboutlinkInformation about the current resource.
accountslinkA collection of brand accounts, that is, a brand's ledger.
memberslinkA collection of brand members.
orderslink...
promoslinkA collection of brand promotions.
recordslinkA collection of 'record'.
tallylinkPeriodic aggregated budget activity information, by brand and type of activity.
throttleslinkA collection of 'throttle'.
Forms
editformA form for updating a resource.

team-members


api.loadConcept('team-members');

Status 200

{
    "pageOrder": "asc",
    "itemsLimit": 50,
    "collectionOf": "member",
    "pageOf": "/team/104/members",
    "brand_id": 104,
    "@type": "members",
    "@id": "/team/104/members",
    "member": [
        "/team/104/members?member_id=53",
        "/team/104/members?member_id=55"
    ]
}

A collection of team-member.

PropertyTypeDescription
@idstring...
@typestring...
brand_idinteger(deprecated)
collectionOfstringThe term used for the collection item. For example, instead of promos.items, you could use promos.promo or promos[promos.collectionOf].
itemsLimitintegerThe maximum number of items that is returned in a collection page. To request more than the itemsLimit, make subsequent requests using the collection's 'next' or 'prev' link.
pageOfstringThe '@id' of the collection to which the current page belongs. In other words, this is the link to the default collection resource without pagination.
pageOrderstringEither 'asc' or 'desc' based on item id's.
Links
memberlinkA user that is a member of a brand.

team-member


api.loadConcept('team-member');

Status 200

[
    {
        "id": 53,
        "user_id": 21,
        "role": "admin",
        "hours": 0,
        "created": "2015-01-05 11:53:31",
        "name": "User One",
        "joined": "2015-11-17 04:15:14",
        "revoked": null,
        "@id": "/team/104/members?member_id=53",
        "brand": "/team/104"
    }
]

A team member.

PropertyTypeDescription
@idstring...
createdstringThe date and time when a resource was created, in the form of `YYYY-MM-DD hh:mm:ss`.
hoursintegerThe number of hours per week that a member spends towards contributing to the team goals.
idintegerA numeric identifier for a resource, that is unique for a given resource type.
joinedstringThe date when a user joined a team.
namestringThe name of the resource.
revokedNULLThe date when a relation between resources was ended, such as when a member leaves a team.
rolestringA user's role within the given context, such as a team member role or a payment role.
user_idinteger(deprecated)
Links
brandlinkThe currency issuer related to this resource.

team-accounts


api.loadConcept('team-accounts');

Status 200

{
    "pageOrder": "asc",
    "itemsLimit": 50,
    "collectionOf": "account",
    "pageOf": "/team/104/accounts",
    "brand_id": 104,
    "@type": "accounts",
    "@id": "/team/104/accounts",
    "account": [
        "/team/104/accounts?account_id=92",
        "/team/104/accounts?account_id=93",
        "/team/104/accounts?account_id=94"
    ]
}

A collection of team-account, also referred to as a team ledger.

PropertyTypeDescription
@idstring...
@typestring...
brand_idinteger(deprecated)
collectionOfstringThe term used for the collection item. For example, instead of promos.items, you could use promos.promo or promos[promos.collectionOf].
itemsLimitintegerThe maximum number of items that is returned in a collection page. To request more than the itemsLimit, make subsequent requests using the collection's 'next' or 'prev' link.
pageOfstringThe '@id' of the collection to which the current page belongs. In other words, this is the link to the default collection resource without pagination.
pageOrderstringEither 'asc' or 'desc' based on item id's.
Links
accountlinkA brand account. An account with a sign=-1 is a revenue budget that holds debits, with a normal balance of <= 0, to be used for receiving payments. An account with a sign=1 is an expense budget that holds credits, with a normal balance >=0, to be used as payment.

team-account


api.loadConcept('team-account');

Status 200

[
    {
        "id": 92,
        "name": "Main Revenue",
        "balance": -1399.98,
        "unit": "hour",
        "authcode": "cftix",
        "created": "2015-01-05 11:53:31",
        "throttle_id": 0,
        "@id": "/team/104/accounts?account_id=92",
        "brand": "/team/104"
    }
]

Accounts belonging to a team.

PropertyTypeDescription
@idstring...
authcodestringThe permissions related to a resource. In the case of an account or an accountholding, the authcode encodes which transaction activities are allowed based on the intersecting values between account.authcode and holder.authcode. The presence of the following characters in the authcode signify the corresponding permission: 'c' to add budget, 'f' to act as a budget transfer originator, 't' to act as a buget transfer recipient, 'i' for internal budget use within a brand, 'x' for external budget use between brands.
balancedoubleThe available amount related to a resource, such as an account balance.
createdstringThe date and time when a resource was created, in the form of `YYYY-MM-DD hh:mm:ss`.
idintegerA numeric identifier for a resource, that is unique for a given resource type.
namestringThe name of the resource.
throttle_idinteger(deprecated)
unitstringThe accounting-unit of a budget, also the currency unit. The only possible value right now is XTE.
Links
brandlinkThe currency issuer related to this resource.

team-promos


api.loadConcept('team-promos');

Status 200

{
    "pageOrder": "desc",
    "itemsLimit": 50,
    "collectionOf": "promo",
    "pageOf": "/brand/104/promos",
    "brand_id": 104,
    "@type": "brandPromos",
    "@id": "/brand/104/promos",
    "add": "/form/promo-add",
    "promo": [
        "/promo/1",
        "/promo/3",
        "/promo/4"
    ]
}

A collection of team-promo.

PropertyTypeDescription
@idstring...
@typestring...
brand_idinteger(deprecated)
collectionOfstringThe term used for the collection item. For example, instead of promos.items, you could use promos.promo or promos[promos.collectionOf].
itemsLimitintegerThe maximum number of items that is returned in a collection page. To request more than the itemsLimit, make subsequent requests using the collection's 'next' or 'prev' link.
pageOfstringThe '@id' of the collection to which the current page belongs. In other words, this is the link to the default collection resource without pagination.
pageOrderstringEither 'asc' or 'desc' based on item id's.
Links
promolinkA brand promotion, used to advertise anything that could be the target of a payment.
Forms
addformA form for adding a resource to a collection, or for adding to a resource's tracked quantity.

team-promos-add


api.loadId(currResource['add']).then(...);

Status 200

// the response returned by promise.then
{
    "title": "Add",
    "@type": "form",
    "@id": "/form/promo-add",
    "method": "POST",
    "inputs": {
        "required": [
            "name",
            "description",
            "amount",
            "holder_id"
        ],
        "optional": [
            "imageURL",
            "infoURL",
            "expires",
            "by_all_limit",
            "by_brand_limit",
            "by_user_limit",
            "by_user_wait",
            "keyword"
        ]
    }
}

Add

PropertyValue
methodPOST
inputs required["name","description","amount","holder_id"]
inputs optional["imageURL","infoURL","expires","by_all_limit","by_brand_limit","by_user_limit","by_user_wait","keyword"]

team-promos-add-0

var currResource = {
    "@id": "/brand/104/promos"
};

api.submit(currResource, 'add', {
    "name": "product promo {hex}",
    "description": "a brand 104 promo {hex}",
    "amount": 5.43,
    "holder_id": 41
}, successFxn, errorFxn);

Example: should allow a brand member to add a promo specification

Status 200

{
    "name": "product promo {hex}",
    "description": "a brand 104 promo {hex}",
    "amount": 5.43,
    "promo_id": 4,
    "relay": {
        "amount_min": 5.43,
        "amount_max": 5.43,
        "txntype": "pn",
        "secret": "eb11",
        "by_all_limit": 25,
        "by_brand_limit": 5,
        "by_user_limit": 2,
        "by_user_wait": 24,
        "relay_id": 6
    },
    "relay_id": 6
}

team-promos-add-1

var currResource = {
    "@id": "/brand/105/promos"
};

api.submit(currResource, 'add', {
    "name": "product promo {hex}",
    "description": "a brand 105 promo {hex}",
    "amount": 3.45
}, successFxn, errorFxn);

Example: should NOT allow a non-brand member to add a promo specification

Status 403

{
    "@context": "/api/ref/context.php",
    "error": "The requester is not a member of brand #105.",
    "hints": [

    ],
    "@graph": [

    ],
    "requestURI": "/brand/105/promos"
}

team-promos-add-2

var currResource = {
    "@id": "/promo/collection"
};

api.submit(currResource, 'add', {
    "name": "product promo {hex}",
    "description": "a brand 104 promo {hex}",
    "amount": 5.43,
    "holder_id": 41
}, successFxn, errorFxn);

Example: should allow a brand member to add using the promo/collection endpoint

Status 200

{
    "name": "product promo {hex}",
    "description": "a brand 104 promo {hex}",
    "amount": 5.43,
    "promo_id": 3,
    "relay": {
        "amount_min": 5.43,
        "amount_max": 5.43,
        "txntype": "pn",
        "secret": "1123d",
        "by_all_limit": 25,
        "by_brand_limit": 5,
        "by_user_limit": 2,
        "by_user_wait": 24,
        "relay_id": 5
    },
    "relay_id": 5
}

team-promo


api.loadConcept('team-promo');

Status 200

[
    {
        "id": 1,
        "name": "Test promo",
        "description": "A brand #104 promo",
        "amount": 25,
        "imageURL": null,
        "infoURL": "http://tatag.dev/ad/1",
        "created": "2014-12-31 16:00:00",
        "updated": null,
        "expires": null,
        "keyword": "software",
        "brand": "/brand/104",
        "relay": "/relay/1",
        "@id": "/promo/1",
        "@type": "promo",
        "payURL": "http://tatag.dev/for/software-1",
        "code": "software-1",
        "promoPage": "http://tatag.dev/ad/1",
        "edit": "/form/promo-edit"
    }
]

A promo that has been created by a team, intended to announce or advertise products, services, and projects that any user could help pay for.

PropertyTypeDescription
@idstring...
@typestring...
amountintegerA numeric value that quantifies an important aspect of a resource. For example, in the context of a promo or transaction record, the amount may be a product price or a suggested donation amount.
codestringAn alpha-numeric string that a payment recipient shares with a payor to authorize a payment or promo use.
createdstringThe date and time when a resource was created, in the form of `YYYY-MM-DD hh:mm:ss`.
descriptionstring...
expiresNULLThe date after which a given resource will no longer be available. For example, a promo may expire after a week.
idintegerA numeric identifier for a resource, that is unique for a given resource type.
imageURLNULLIf given, a user interface provider may use this link to display a brand icon or promo image.
infoURLstringExternal web page about a resource.
keywordstringIn the context of a relay, this is the prefix to be used with a relay id, such as the 'food-' in the relay token value of 'food-645'. This keyword is assigned by the user when creating a promo, and also helps to counter (but not prevent) spammy transaction offers by making it harder to guess the full value of a relay token.
namestringThe name of the resource.
payURLstringA URL that, when clicked, is intended to automatically open the tatag.cc wallet of a payor.
promoPagestringThe tatag.cc-hosted web page about the promo. An infoURL, when available, should be preferred as an external link.
updatedNULLThe UNIX timestamp when a resource was last updated.
Links
brandlinkThe currency issuer related to this resource.
relaylinkA token that is used to preauthorize the use of a recipient account.
Forms
editformA form for updating a resource.

team-promo-edit


api.loadId(currResource['edit']).then(...);

Status 200

// the response returned by promise.then
{
    "title": "Edit",
    "@type": "form",
    "@id": "/form/promo-edit",
    "method": "POST",
    "inputs": {
        "required": [

        ],
        "optional": [
            "name",
            "description",
            "amount",
            "imageURL",
            "infoURL",
            "expires",
            "keyword"
        ]
    }
}

Edit

PropertyValue
methodPOST
inputs required[]
inputs optional["name","description","amount","imageURL","infoURL","expires","keyword"]

team-promo-edit-0

var currResource = {
    "@id": "/promo/1"
};

api.submit(currResource, 'edit', {
    "name": "{hex}",
    "amount": 8.97
}, successFxn, errorFxn);

Example: should allow a brand admin to edit a promo specification

Status 200

{
    "name": "{hex}",
    "amount": 8.97
}

team-promo-edit-1

var currResource = {
    "@id": "/promo/2"
};

api.submit(currResource, 'edit', {
    "name": "{hex}",
    "amount": 7.98
}, successFxn, errorFxn);

Example: should NOT allow a non-brand admin to edit a promo specification

Status 403

{
    "@context": "/api/ref/context.php",
    "error": "The user is not a member of the brand that owns this promo and does not have accees to its details.",
    "hints": [

    ],
    "@graph": [

    ],
    "requestURI": "/promo/2"
}

team-throttles


api.loadConcept('team-throttles');

Status 200

{
    "brand_id": 104,
    "@type": "throttles",
    "@id": "/team/104/throttles",
    "collectionOf": "throttle",
    "throttle": [
        {
            "period": 172800,
            "by_all": 100,
            "by_brand": 20,
            "by_user": 2,
            "created": "2015-02-24 02:48:00",
            "updated": null,
            "ended": null,
            "productURL": null,
            "id": 1,
            "@id": "/throttle/1",
            "brand": "/team/104"
        },
        {
            "period": 3600,
            "by_all": 10,
            "by_brand": 2,
            "by_user": 1,
            "created": "2015-02-24 02:48:00",
            "updated": null,
            "ended": null,
            "productURL": null,
            "id": 2,
            "@id": "/throttle/2",
            "brand": "/team/104"
        },
        {
            "period": 9999999,
            "by_all": 100,
            "by_brand": 20,
            "by_user": 2,
            "created": "2015-02-24 02:48:00",
            "updated": null,
            "ended": null,
            "productURL": null,
            "id": 3,
            "@id": "/throttle/3",
            "brand": "/team/104"
        }
    ]
}

A collection of team-throttle.

PropertyTypeDescription
@idstring...
@typestring...
brand_idinteger(deprecated)
collectionOfstringThe term used for the collection item. For example, instead of promos.items, you could use promos.promo or promos[promos.collectionOf].
Links
throttlelinkA limit on how much an account may be used for transactions for a given period, specified as amount per brand, amount per user, and amount by all.

team-throttle


api.loadConcept('team-throttle');

Status 200

[
    {
        "period": 172800,
        "by_all": 100,
        "by_brand": 20,
        "by_user": 2,
        "created": "2015-02-24 02:48:00",
        "updated": null,
        "ended": null,
        "productURL": null,
        "id": 1,
        "@id": "/throttle/1",
        "brand": "/team/104"
    }
]

A set of periodic limits imposed on inflows or outflows from a team account.

PropertyTypeDescription
@idstring...
by_allinteger...
by_brandinteger...
by_userinteger...
createdstringThe date and time when a resource was created, in the form of `YYYY-MM-DD hh:mm:ss`.
endedNULLThe date of resource or relation deactivation, formatted as `YYYY-MM-DD hh:mm:ss`.
idintegerA numeric identifier for a resource, that is unique for a given resource type.
periodintegerThe time period that applies to a resource.
productURLNULL...
updatedNULLThe UNIX timestamp when a resource was last updated.
Links
brandlinkThe currency issuer related to this resource.

team-orders


api.loadConcept('team-orders');

Status 200

{
    "pageOrder": "asc",
    "itemsLimit": 50,
    "collectionOf": "order",
    "pageOf": "/team/104/orders",
    "@type": "teamOrders",
    "brand_id": 104,
    "@id": "/team/104/orders",
    "order": [
        "/team/104/orders?record_id=40"
    ],
    "update": "/form/order-update"
}

blah blah blah

PropertyTypeDescription
@idstring...
@typestring...
brand_idinteger(deprecated)
collectionOfstringThe term used for the collection item. For example, instead of promos.items, you could use promos.promo or promos[promos.collectionOf].
itemsLimitintegerThe maximum number of items that is returned in a collection page. To request more than the itemsLimit, make subsequent requests using the collection's 'next' or 'prev' link.
pageOfstringThe '@id' of the collection to which the current page belongs. In other words, this is the link to the default collection resource without pagination.
pageOrderstringEither 'asc' or 'desc' based on item id's.
Links
orderlink...
Forms
updateform...

team-order


api.loadConcept('team-order');

Status 200

[
    {
        "record_id": 40,
        "created": "2015-11-18 07:21:15",
        "amount": 25,
        "note": "for ad-1",
        "order_step": 0,
        "updated": "2015-11-18 23:10:25",
        "@id": "/team/104/orders?record_id=40",
        "update": "/form/order-update",
        "promo": "/promo/1",
        "user": "/user/21/about",
        "from": "/brand/104/about"
    }
]

blah blah blah

PropertyTypeDescription
@idstring...
amountintegerA numeric value that quantifies an important aspect of a resource. For example, in the context of a promo or transaction record, the amount may be a product price or a suggested donation amount.
createdstringThe date and time when a resource was created, in the form of `YYYY-MM-DD hh:mm:ss`.
fromstring...
notestringA short text used to annotate a resource such as a transaction record.
order_stepinteger...
record_idinteger(deprecated)
updatedstringThe UNIX timestamp when a resource was last updated.
userstringA person-resource.
Links
promolinkA brand promotion, used to advertise anything that could be the target of a payment.
Forms
updateform...

team-order-update


api.loadId(currResource['update']).then(...);

Status 200

// the response returned by promise.then
{
    "title": "Update the status of an order",
    "@type": "form",
    "@id": "/form/order-update",
    "method": "POST",
    "inputs": {
        "required": [
            "order_step"
        ]
    }
}

Update the status of an order

PropertyValue
methodPOST
inputs required["order_step"]
inputs optionalnull

team-order-update-0

var currResource = {
    "@id": "/team/104/orders?record_id=34"
};

api.submit(currResource, 'update', {
    "order_step": 5
}, successFxn, errorFxn);

Example: should allow a brand member to update an order_step

Status 200

{
    "order_step": 5
}

team-order-update-1

var currResource = {
    "@id": "/team/105/orders?record_id=37"
};

api.submit(currResource, 'update', {
    "order_step": 5
}, successFxn, errorFxn);

Example: should NOT allow a non-brand member to update an order step

Status 403

{
    "@context": "/api/ref/context.php",
    "error": "Only members or admins of brand #105 can view its orders.",
    "hints": [

    ],
    "@graph": [

    ],
    "requestURI": "/team/105/orders?record_id=37"
}

Admin Resources

The admins of a brand share access to these resources. The accessible resources are based on the admin status of the currently logged-in user.

admin-brand


api.loadConcept('admin-brand');

Status 200

[
    {
        "id": 104,
        "@type": "brand",
        "@id": "/brand/104",
        "role": "admin",
        "name": "abc",
        "brand_name": "abc",
        "members": "/brand/104/members",
        "accounts": "/brand/104/accounts",
        "about": "/brand/104/about",
        "promos": "/brand/104/promos",
        "records": "/budget/104/records",
        "throttles": "/budget/104/throttles",
        "tally": "/brand/104/tally",
        "edit": "/form/brand-edit"
    }
]

A brand that is administered by the current user.

PropertyTypeDescription
@idstring...
@typestring...
brand_namestring(deprecated) The name of the related brand. Use the (sub)resource 'name' instead.
idintegerA numeric identifier for a resource, that is unique for a given resource type.
namestringThe name of the resource.
rolestringA user's role within the given context, such as a team member role or a payment role.
Links
aboutlinkInformation about the current resource.
accountslinkA collection of brand accounts, that is, a brand's ledger.
memberslinkA collection of brand members.
promoslinkA collection of brand promotions.
recordslinkA collection of 'record'.
tallylinkPeriodic aggregated budget activity information, by brand and type of activity.
throttleslinkA collection of 'throttle'.
Forms
editformA form for updating a resource.

admin-brand-edit


api.loadId(currResource['edit']).then(...);

Status 200

// the response returned by promise.then
{
    "title": "Edit",
    "@type": "form",
    "@id": "/form/brand-edit",
    "method": "POST",
    "inputs": {
        "required": [

        ],
        "optional": [
            "name",
            "url",
            "mission",
            "description",
            "url",
            "advisor",
            "type_system",
            "type_id",
            "country_code",
            "area_code",
            "logo"
        ]
    }
}

Edit

PropertyValue
methodPOST
inputs required[]
inputs optional["name","url","mission","description","url","advisor","type_system","type_id","country_code","area_code","logo"]

admin-brand-edit-0

var currResource = {
    "@id": "/brand/104"
};

api.submit(currResource, 'edit', {
    "mission": "another mission -{xtime}",
    "description": "another description -{xtime}"
}, successFxn, errorFxn);

Example: should allow an admin to edit a brand's info

Status 200

{
    "mission": "another mission -1453364051",
    "description": "another description -1453364051"
}

admin-brand-edit-1

var currResource = {
    "@id": "/brand/105"
};

api.submit(currResource, 'edit', {
    "mission": "non-admin's brand mission -{xtime}",
    "description": "non-admin's brand description -{xtime}"
}, successFxn, errorFxn);

Example: should NOT allow a non-admin to edit a brand's alias

Status 403

{
    "@context": "/api/ref/context.php",
    "error": "The requester is not an admin for brand #105.",
    "hints": [

    ],
    "@graph": [

    ],
    "requestURI": "/brand/105"
}

admin-members


api.loadConcept('admin-members');

Status 200

{
    "pageOrder": "asc",
    "itemsLimit": 50,
    "collectionOf": "member",
    "pageOf": "/brand/104/members",
    "brand_id": 104,
    "@type": "brandMembers",
    "@id": "/brand/104/members",
    "add": "/form/member-add",
    "member": [
        "/brand/104/members?member_id=53",
        "/brand/104/members?member_id=55"
    ],
    "edit": "/form/admin-member-edit"
}

A collection of admin-member.

PropertyTypeDescription
@idstring...
@typestring...
brand_idinteger(deprecated)
collectionOfstringThe term used for the collection item. For example, instead of promos.items, you could use promos.promo or promos[promos.collectionOf].
itemsLimitintegerThe maximum number of items that is returned in a collection page. To request more than the itemsLimit, make subsequent requests using the collection's 'next' or 'prev' link.
pageOfstringThe '@id' of the collection to which the current page belongs. In other words, this is the link to the default collection resource without pagination.
pageOrderstringEither 'asc' or 'desc' based on item id's.
Links
memberlinkA user that is a member of a brand.
Forms
addformA form for adding a resource to a collection, or for adding to a resource's tracked quantity.
editformA form for updating a resource.

admin-members-add


api.loadId(currResource['add']).then(...);

Status 200

// the response returned by promise.then
{
    "title": "Add a member",
    "@type": "form",
    "@id": "/form/member-add",
    "method": "POST",
    "inputs": {
        "required": [
            "user_id",
            "role",
            "hours"
        ],
        "optional": [

        ]
    }
}

Add a member

PropertyValue
methodPOST
inputs required["user_id","role","hours"]
inputs optional[]

admin-members-add-0

var currResource = {
    "@id": "/brand/104/members"
};

api.submit(currResource, 'add', {
    "user_id": 24,
    "role": "dev-{xtime}",
    "hours": "{random}"
}, successFxn, errorFxn);

Example: should allow an admin to add a brand member

Status 200

{
    "user_id": 24,
    "role": "dev-1453364051",
    "hours": 3,
    "member_id": 56
}

admin-members-add-1

var currResource = {
    "@id": "/brand/105/members"
};

api.submit(currResource, 'add', {
    "user_id": 24,
    "role": "dev-{xtime}",
    "hours": "{random}"
}, successFxn, errorFxn);

Example: should NOT allow a non-admin to add a member

Status 403

{
    "@context": "/api/ref/context.php",
    "error": "The requester is not an admin for brand #105.",
    "hints": [

    ],
    "@graph": [

    ],
    "requestURI": "/brand/105/members"
}

admin-member


api.loadConcept('admin-member');

Status 200

[
    {
        "id": 53,
        "user_id": 21,
        "role": "admin",
        "hours": 0,
        "created": "2015-01-05 11:53:31",
        "name": "User One",
        "joined": "2015-11-17 04:15:14",
        "revoked": null,
        "@id": "/brand/104/members?member_id=53",
        "holdings": "/member/53/accounts",
        "edit": "/form/admin-member-edit",
        "brand": "/brand/104"
    }
]

A brand membership that is admininistered by the current user.

PropertyTypeDescription
@idstring...
createdstringThe date and time when a resource was created, in the form of `YYYY-MM-DD hh:mm:ss`.
hoursintegerThe number of hours per week that a member spends towards contributing to the team goals.
idintegerA numeric identifier for a resource, that is unique for a given resource type.
joinedstringThe date when a user joined a team.
namestringThe name of the resource.
revokedNULLThe date when a relation between resources was ended, such as when a member leaves a team.
rolestringA user's role within the given context, such as a team member role or a payment role.
user_idinteger(deprecated)
Links
brandlinkThe currency issuer related to this resource.
holdingslinkA collection of accountholdings.
Forms
editformA form for updating a resource.

admin-member-edit


api.loadId(currResource['edit']).then(...);

Status 200

// the response returned by promise.then
{
    "title": "Edit",
    "@type": "form",
    "@id": "/form/admin-member-edit",
    "method": "POST",
    "inputs": {
        "required": [

        ],
        "optional": [
            "role",
            "hours"
        ]
    }
}

Edit

PropertyValue
methodPOST
inputs required[]
inputs optional["role","hours"]

admin-member-edit-0

var currResource = {
    "@id": "/brand/104/members?member_id=55"
};

api.submit(currResource, 'edit', {
    "role": "assistant -{xtime}",
    "hours": "{random}"
}, successFxn, errorFxn);

Example: should allow an admin to edit a member's info

Status 200

{
    "items": [

    ],
    "pageOrder": "asc",
    "itemsLimit": 50,
    "collectionOf": "member",
    "pageOf": null,
    "brand_id": 104,
    "@type": "brandMembers",
    "@id": "/brand/104/members",
    "role": "assistant -1453364051",
    "hours": 464
}

admin-member-edit-1

var currResource = {
    "@id": "/brand/105/members?member_id=54"
};

api.submit(currResource, 'edit', {
    "role": "assistant -{xtime}",
    "hours": "{random}"
}, successFxn, errorFxn);

Example: should NOT allow a non-admin to edit a member's info

Status 403

{
    "@context": "/api/ref/context.php",
    "error": "The requester is not an admin for brand #105.",
    "hints": [

    ],
    "@graph": [

    ],
    "requestURI": "/brand/105/members?member_id=54"
}

admin-member-holdings


api.loadConcept('admin-member-holdings');

Status 200

{
    "id": 53,
    "pageOrder": "asc",
    "itemsLimit": 50,
    "collectionOf": "holding",
    "pageOf": "/member/53/accounts",
    "user_id": 21,
    "role": "admin",
    "hours": 0,
    "created": "2015-01-05 11:53:31",
    "brand": "/brand/104",
    "@type": "memberAccounts",
    "@id": "/member/53/accounts",
    "add": "/form/holder-add",
    "holding": [
        "/member/53/accounts?holder_id=41",
        "/member/53/accounts?holder_id=42",
        "/member/53/accounts?holder_id=43"
    ],
    "edit": "/form/admin-holder-edit"
}

A collection of admin-member-holding.

PropertyTypeDescription
@idstring...
@typestring...
collectionOfstringThe term used for the collection item. For example, instead of promos.items, you could use promos.promo or promos[promos.collectionOf].
createdstringThe date and time when a resource was created, in the form of `YYYY-MM-DD hh:mm:ss`.
hoursintegerThe number of hours per week that a member spends towards contributing to the team goals.
idintegerA numeric identifier for a resource, that is unique for a given resource type.
itemsLimitintegerThe maximum number of items that is returned in a collection page. To request more than the itemsLimit, make subsequent requests using the collection's 'next' or 'prev' link.
pageOfstringThe '@id' of the collection to which the current page belongs. In other words, this is the link to the default collection resource without pagination.
pageOrderstringEither 'asc' or 'desc' based on item id's.
rolestringA user's role within the given context, such as a team member role or a payment role.
user_idinteger(deprecated)
Links
brandlinkThe currency issuer related to this resource.
holdinglinkAn accountholding.
Forms
addformA form for adding a resource to a collection, or for adding to a resource's tracked quantity.
editformA form for updating a resource.

admin-member-holdings-add


api.loadId(currResource['add']).then(...);

Status 200

// the response returned by promise.then
{
    "title": "Add an account holder",
    "@type": "form",
    "@id": "/form/holder-add",
    "method": "POST",
    "inputs": {
        "required": [
            "user_id",
            "account_id",
            "authcode"
        ],
        "optional": [

        ]
    }
}

Add an account holder

PropertyValue
methodPOST
inputs required["user_id","account_id","authcode"]
inputs optional[]

admin-member-holdings-add-0

var currResource = {
    "@id": "/member/55/accounts"
};

api.submit(currResource, 'add', {
    "user_id": 24,
    "account_id": 92,
    "authcode": "cftix"
}, successFxn, errorFxn);

Example: should allow an admin to add a new accountholder

Status 200

{
    "items": [

    ],
    "pageOrder": "asc",
    "itemsLimit": 50,
    "collectionOf": "holder",
    "pageOf": null,
    "brand_id": 104,
    "@type": "brandHolders",
    "@id": "/brand/104/holders",
    "user_id": 24,
    "account_id": 94,
    "authcode": "cftix",
    "limkey": "abc",
    "holder_id": 46
}

admin-member-holdings-add-1

var currResource = {
    "@id": "/member/54/accounts"
};

api.submit(currResource, 'add', {
    "user_id": 22,
    "account_id": 92,
    "authcode": "cftix"
}, successFxn, errorFxn);

Example: should NOT allow a non-admin to add a new accountholder

Status 403

{
    "@context": "/api/ref/context.php",
    "error": "The requester is not an admin for brand #105.",
    "hints": [

    ],
    "@graph": [

    ],
    "requestURI": "/brand/105/holders"
}

admin-member-holding


api.loadConcept('admin-member-holding');

Status 200

[
    {
        "id": 41,
        "authcode": "cftix",
        "created": "2015-01-05 11:53:31",
        "account": "/account/92",
        "@id": "/member/53/accounts?holder_id=41",
        "edit": "/form/admin-holder-edit"
    }
]

An accountholding by a brand member that is administered by the current user.

PropertyTypeDescription
@idstring...
authcodestringThe permissions related to a resource. In the case of an account or an accountholding, the authcode encodes which transaction activities are allowed based on the intersecting values between account.authcode and holder.authcode. The presence of the following characters in the authcode signify the corresponding permission: 'c' to add budget, 'f' to act as a budget transfer originator, 't' to act as a buget transfer recipient, 'i' for internal budget use within a brand, 'x' for external budget use between brands.
createdstringThe date and time when a resource was created, in the form of `YYYY-MM-DD hh:mm:ss`.
idintegerA numeric identifier for a resource, that is unique for a given resource type.
Links
accountlinkA brand account. An account with a sign=-1 is a revenue budget that holds debits, with a normal balance of <= 0, to be used for receiving payments. An account with a sign=1 is an expense budget that holds credits, with a normal balance >=0, to be used as payment.
Forms
editformA form for updating a resource.

admin-member-holding-edit


api.loadId(currResource['edit']).then(...);

Status 200

// the response returned by promise.then
{
    "title": "Edit",
    "@type": "form",
    "@id": "/form/admin-holder-edit",
    "method": "POST",
    "inputs": {
        "required": [
            "authcode"
        ],
        "optional": [

        ]
    }
}

Edit

PropertyValue
methodPOST
inputs required["authcode"]
inputs optional[]

admin-member-holding-edit-0

var currResource = {
    "@id": "/brand/104/holders?holder_id=43"
};

api.submit(currResource, 'edit', {
    "authcode": "ftix -w"
}, successFxn, errorFxn);

Example: should allow an admin to edit a holder's authcode

Status 200

{
    "id": 55,
    "items": [

    ],
    "pageOrder": "asc",
    "itemsLimit": 50,
    "collectionOf": "holding",
    "pageOf": null,
    "user_id": 23,
    "role": "assistant -1453364051",
    "hours": 464,
    "created": "2015-01-05 11:53:31",
    "brand": "/brand/104",
    "@type": "memberAccounts",
    "@id": "/member/55/accounts",
    "authcode": "ftix -w"
}

admin-member-holding-edit-1

var currResource = {
    "@id": "/brand/104/holders?holder_id=44"
};

api.submit(currResource, 'edit', {
    "name": "my -{xtime}",
    "authcode": "{random}"
}, successFxn, errorFxn);

Example: should NOT allow a non-admin to edit an account's info

Status 403

{
    "@context": "/api/ref/context.php",
    "error": "These parameters may not be set by the user: [\"name\"].",
    "hints": [

    ],
    "@graph": [

    ],
    "requestURI": "/member/55/accounts?holder_id=45"
}

admin-accounts


api.loadConcept('admin-accounts');

Status 200

{
    "pageOrder": "asc",
    "itemsLimit": 50,
    "collectionOf": "account",
    "pageOf": "/brand/104/accounts",
    "brand_id": 104,
    "@type": "brandAccounts",
    "@id": "/brand/104/accounts",
    "add": "/form/account-add",
    "account": [
        "/brand/104/accounts?account_id=92",
        "/brand/104/accounts?account_id=93",
        "/brand/104/accounts?account_id=94"
    ],
    "edit": "/form/admin-account-edit"
}

A collection of admin-account.

PropertyTypeDescription
@idstring...
@typestring...
brand_idinteger(deprecated)
collectionOfstringThe term used for the collection item. For example, instead of promos.items, you could use promos.promo or promos[promos.collectionOf].
itemsLimitintegerThe maximum number of items that is returned in a collection page. To request more than the itemsLimit, make subsequent requests using the collection's 'next' or 'prev' link.
pageOfstringThe '@id' of the collection to which the current page belongs. In other words, this is the link to the default collection resource without pagination.
pageOrderstringEither 'asc' or 'desc' based on item id's.
Links
accountlinkA brand account. An account with a sign=-1 is a revenue budget that holds debits, with a normal balance of <= 0, to be used for receiving payments. An account with a sign=1 is an expense budget that holds credits, with a normal balance >=0, to be used as payment.
Forms
addformA form for adding a resource to a collection, or for adding to a resource's tracked quantity.
editformA form for updating a resource.

admin-accounts-add


api.loadId(currResource['add']).then(...);

Status 200

// the response returned by promise.then
{
    "title": "Add an account",
    "@type": "form",
    "@id": "/form/account-add",
    "method": "POST",
    "inputs": {
        "required": [
            "name",
            "authcode",
            "unit",
            "sign"
        ],
        "optional": [

        ]
    }
}

Add an account

PropertyValue
methodPOST
inputs required["name","authcode","unit","sign"]
inputs optional[]

admin-accounts-add-0

var currResource = {
    "@id": "/brand/104/accounts"
};

api.submit(currResource, 'add', {
    "name": "test -{xtime}",
    "authcode": "cftix",
    "unit": "hour"
}, successFxn, errorFxn);

Example: should allow an admin to add a new account

Status 200

{
    "items": [

    ],
    "pageOrder": "asc",
    "itemsLimit": 50,
    "collectionOf": "account",
    "pageOf": null,
    "brand_id": 104,
    "@type": "brandAccounts",
    "@id": "/brand/104/accounts",
    "name": "test -1453364051",
    "authcode": "cftix",
    "unit": "hour",
    "sign": 1,
    "account_id": 116
}

admin-accounts-add-1

var currResource = {
    "@id": "/brand/105/accounts"
};

api.submit(currResource, 'add', {
    "name": "test -{xtime}",
    "authcode": "cftix",
    "unit": "hour"
}, successFxn, errorFxn);

Example: should NOT allow a non-admin to add an account

Status 403

{
    "@context": "/api/ref/context.php",
    "error": "The requester is not an admin for brand #105.",
    "hints": [

    ],
    "@graph": [

    ],
    "requestURI": "/brand/105/accounts"
}

admin-account


api.loadConcept('admin-account');

Status 200

[
    {
        "id": 92,
        "name": "Main Revenue",
        "balance": -1399.98,
        "unit": "hour",
        "authcode": "cftix",
        "created": "2015-01-05 11:53:31",
        "throttle_id": 0,
        "@id": "/brand/104/accounts?account_id=92",
        "holders": "/account/92/holders",
        "edit": "/form/admin-account-edit",
        "brand": "/brand/104"
    }
]

A brand account that is administered by the current user.

PropertyTypeDescription
@idstring...
authcodestringThe permissions related to a resource. In the case of an account or an accountholding, the authcode encodes which transaction activities are allowed based on the intersecting values between account.authcode and holder.authcode. The presence of the following characters in the authcode signify the corresponding permission: 'c' to add budget, 'f' to act as a budget transfer originator, 't' to act as a buget transfer recipient, 'i' for internal budget use within a brand, 'x' for external budget use between brands.
balancedoubleThe available amount related to a resource, such as an account balance.
createdstringThe date and time when a resource was created, in the form of `YYYY-MM-DD hh:mm:ss`.
idintegerA numeric identifier for a resource, that is unique for a given resource type.
namestringThe name of the resource.
throttle_idinteger(deprecated)
unitstringThe accounting-unit of a budget, also the currency unit. The only possible value right now is XTE.
Links
brandlinkThe currency issuer related to this resource.
holderslinkA collection of accountholders.
Forms
editformA form for updating a resource.

admin-account-edit


api.loadId(currResource['edit']).then(...);

Status 200

// the response returned by promise.then
{
    "title": "Edit",
    "@type": "form",
    "@id": "/form/admin-account-edit",
    "method": "POST",
    "inputs": {
        "required": [

        ],
        "optional": [
            "name",
            "authcode",
            "throttle_id"
        ]
    }
}

Edit

PropertyValue
methodPOST
inputs required[]
inputs optional["name","authcode","throttle_id"]

admin-account-edit-0

var currResource = {
    "@id": "/brand/104/accounts?account_id=94"
};

api.submit(currResource, 'edit', {
    "name": "my -{xtime}",
    "authcode": "ft -w"
}, successFxn, errorFxn);

Example: should allow an admin to edit an account's info

Status 200

{
    "items": [

    ],
    "pageOrder": "asc",
    "itemsLimit": 50,
    "collectionOf": "account",
    "pageOf": null,
    "brand_id": 104,
    "@type": "brandAccounts",
    "@id": "/brand/104/accounts",
    "name": "my -1453364051",
    "authcode": "ft -w"
}

admin-account-edit-1

var currResource = {
    "@id": "/brand/105/accounts?account_id=97"
};

api.submit(currResource, 'edit', {
    "name": "my -{xtime}",
    "authcode": "{random}"
}, successFxn, errorFxn);

Example: should NOT allow a non-admin to edit an account's info

Status 403

{
    "@context": "/api/ref/context.php",
    "error": "The requester is not an admin for brand #105.",
    "hints": [

    ],
    "@graph": [

    ],
    "requestURI": "/brand/105/accounts?account_id=97"
}

admin-account-holders


api.loadConcept('admin-account-holders');

Status 200

{
    "id": 92,
    "pageOrder": "asc",
    "itemsLimit": 50,
    "collectionOf": "holder",
    "pageOf": "/account/92/holders",
    "brand": "/brand/104",
    "@type": "accountHolders",
    "@id": "/account/92/holders",
    "add": "/form/holder-add",
    "holder": [
        "/account/92/holders?holder_id=41"
    ]
}

A collection of admin-account-holder.

PropertyTypeDescription
@idstring...
@typestring...
collectionOfstringThe term used for the collection item. For example, instead of promos.items, you could use promos.promo or promos[promos.collectionOf].
idintegerA numeric identifier for a resource, that is unique for a given resource type.
itemsLimitintegerThe maximum number of items that is returned in a collection page. To request more than the itemsLimit, make subsequent requests using the collection's 'next' or 'prev' link.
pageOfstringThe '@id' of the collection to which the current page belongs. In other words, this is the link to the default collection resource without pagination.
pageOrderstringEither 'asc' or 'desc' based on item id's.
Links
brandlinkThe currency issuer related to this resource.
holderlinkAn accountholder.
Forms
addformA form for adding a resource to a collection, or for adding to a resource's tracked quantity.

admin-account-holders-add


api.loadId(currResource['add']).then(...);

Status 200

// the response returned by promise.then
{
    "title": "Add an account holder",
    "@type": "form",
    "@id": "/form/holder-add",
    "method": "POST",
    "inputs": {
        "required": [
            "user_id",
            "account_id",
            "authcode"
        ],
        "optional": [

        ]
    }
}

Add an account holder

PropertyValue
methodPOST
inputs required["user_id","account_id","authcode"]
inputs optional[]

admin-account-holders-add-0

var currResource = {
    "@id": "/member/55/accounts"
};

api.submit(currResource, 'add', {
    "user_id": 24,
    "account_id": 92,
    "authcode": "cftix"
}, successFxn, errorFxn);

Example: should allow an admin to add a new accountholder

Status 200

{
    "items": [

    ],
    "pageOrder": "asc",
    "itemsLimit": 50,
    "collectionOf": "holding",
    "pageOf": null,
    "member_id": 55,
    "brand_id": 104,
    "user_id": 24,
    "role": "staff",
    "hours": 0,
    "created": "2015-01-05 11:53:31",
    "@type": "memberAccounts",
    "@id": "/member/55/accounts",
    "account_id": 92,
    "authcode": "cftix",
    "limkey": "abc",
    "holder_id": 48
}

admin-account-holders-add-1

var currResource = {
    "@id": "/member/54/accounts"
};

api.submit(currResource, 'add', {
    "user_id": 22,
    "account_id": 92,
    "authcode": "cftix"
}, successFxn, errorFxn);

Example: should NOT allow a non-admin to add a new accountholder

Status 403

{
    "@context": "/api/ref/context.php",
    "error": "The requester is not an admin for brand #105.",
    "hints": [

    ],
    "@graph": [

    ],
    "requestURI": "/brand/105/holders"
}

admin-account-holder


api.loadConcept('admin-account-holder');

Status 200

[
    {
        "id": 41,
        "authcode": "cftix",
        "created": "2015-01-05 11:53:31",
        "member_id": 53,
        "account": "/account/92",
        "user": "/user/21/about",
        "@id": "/account/92/holders?holder_id=41",
        "edit": "/form/admin-holder-edit"
    }
]

A holder of a brand account thta is administered by the current user.

PropertyTypeDescription
@idstring...
authcodestringThe permissions related to a resource. In the case of an account or an accountholding, the authcode encodes which transaction activities are allowed based on the intersecting values between account.authcode and holder.authcode. The presence of the following characters in the authcode signify the corresponding permission: 'c' to add budget, 'f' to act as a budget transfer originator, 't' to act as a buget transfer recipient, 'i' for internal budget use within a brand, 'x' for external budget use between brands.
createdstringThe date and time when a resource was created, in the form of `YYYY-MM-DD hh:mm:ss`.
idintegerA numeric identifier for a resource, that is unique for a given resource type.
member_idinteger...
userstringA person-resource.
Links
accountlinkA brand account. An account with a sign=-1 is a revenue budget that holds debits, with a normal balance of <= 0, to be used for receiving payments. An account with a sign=1 is an expense budget that holds credits, with a normal balance >=0, to be used as payment.
Forms
editformA form for updating a resource.

admin-account-holder-edit


api.loadId(currResource['edit']).then(...);

Status 200

// the response returned by promise.then
{
    "title": "Edit",
    "@type": "form",
    "@id": "/form/admin-holder-edit",
    "method": "POST",
    "inputs": {
        "required": [
            "authcode"
        ],
        "optional": [

        ]
    }
}

Edit

PropertyValue
methodPOST
inputs required["authcode"]
inputs optional[]

admin-account-holder-edit-0

var currResource = {
    "@id": "/brand/104/holders?holder_id=43"
};

api.submit(currResource, 'edit', {
    "authcode": "ftix -w"
}, successFxn, errorFxn);

Example: should allow an admin to edit a holder's authcode

Status 200

{
    "items": [

    ],
    "pageOrder": "asc",
    "itemsLimit": 50,
    "collectionOf": "holder",
    "pageOf": null,
    "brand_id": 104,
    "@type": "brandHolders",
    "@id": "/brand/104/holders",
    "authcode": "ftix -w"
}

admin-account-holder-edit-1

var currResource = {
    "@id": "/brand/104/holders?holder_id=44"
};

api.submit(currResource, 'edit', {
    "name": "my -{xtime}",
    "authcode": "{random}"
}, successFxn, errorFxn);

Example: should NOT allow a non-admin to edit an account's info

Status 403

{
    "@context": "/api/ref/context.php",
    "error": "These parameters may not be set by the user: [\"name\"].",
    "hints": [

    ],
    "@graph": [

    ],
    "requestURI": "/brand/104/holders?holder_id=44"
}

admin-about


api.loadConcept('admin-about');

Status 200

{
    "url": "http://tatag.cc/104",
    "brand_id": 104,
    "@type": "brandAbout",
    "@id": "/brand/104/about",
    "name": "abc",
    "description": "for testing",
    "mission": "to be the first brand",
    "created": "2015-01-05 11:53:31",
    "advisor": 0,
    "type_system": "for-profit",
    "type_id": 9,
    "country_code": "USA",
    "area_code": 206,
    "tally": {
        "@type": "budgetTally",
        "added": 1500.11,
        "intrause": 90.76,
        "inflow": 9.37,
        "outflow": 0,
        "revBudget": 1399.98,
        "expBudget": 1409.35,
        "numMembers": 2,
        "totalMemberHours": 0
    }
}

Public information about a brand.

PropertyTypeDescription
@idstring...
@typestring...
advisorinteger...
area_codeintegerThe phone area code where a brand is located. (optional, self-reported)
brand_idinteger(deprecated)
country_codestringThe ISO3 code of a brand location.
createdstringThe date and time when a resource was created, in the form of `YYYY-MM-DD hh:mm:ss`.
descriptionstring...
missionstring...
namestringThe name of the resource.
type_idintegerA brand's self-reported classification.
type_systemstringThe classification system that is used to determine the brand type_id value.
urlstringA link to a web page or image, typically not considered as an API data and therefore not expected to be dereferenced as part of the payload but instead opened as an external link or used in HTML representations.
Links
tallylinkPeriodic aggregated budget activity information, by brand and type of activity.

admin-tally


api.loadConcept('admin-tally');

Status 200

{
    "@type": "budgetTally",
    "@id": "/brand/104/tally",
    "added": 1500.11,
    "intrause": 90.76,
    "inflow": 9.37,
    "outflow": 0,
    "revBudget": 1399.98,
    "expBudget": 1409.35,
    "numMembers": 2,
    "totalMemberHours": 0
}

A summary of a brand's budget balances and activity.

PropertyTypeDescription
@idstring...
@typestring...
addeddouble...
expBudgetdouble...
inflowdouble...
intrausedouble...
numMembersinteger...
outflowinteger...
revBudgetdouble...
totalMemberHoursinteger...

admin-promos


api.loadConcept('admin-promos');

Status 200

{
    "pageOrder": "desc",
    "itemsLimit": 50,
    "collectionOf": "promo",
    "pageOf": "/brand/104/promos",
    "brand_id": 104,
    "@type": "brandPromos",
    "@id": "/brand/104/promos",
    "add": "/form/promo-add",
    "promo": [
        "/promo/1",
        "/promo/3",
        "/promo/4"
    ]
}

A page-colleciton of admin-promo.

PropertyTypeDescription
@idstring...
@typestring...
brand_idinteger(deprecated)
collectionOfstringThe term used for the collection item. For example, instead of promos.items, you could use promos.promo or promos[promos.collectionOf].
itemsLimitintegerThe maximum number of items that is returned in a collection page. To request more than the itemsLimit, make subsequent requests using the collection's 'next' or 'prev' link.
pageOfstringThe '@id' of the collection to which the current page belongs. In other words, this is the link to the default collection resource without pagination.
pageOrderstringEither 'asc' or 'desc' based on item id's.
Links
promolinkA brand promotion, used to advertise anything that could be the target of a payment.
Forms
addformA form for adding a resource to a collection, or for adding to a resource's tracked quantity.

admin-promos-add


api.loadId(currResource['add']).then(...);

Status 200

// the response returned by promise.then
{
    "title": "Add",
    "@type": "form",
    "@id": "/form/promo-add",
    "method": "POST",
    "inputs": {
        "required": [
            "name",
            "description",
            "amount",
            "holder_id"
        ],
        "optional": [
            "imageURL",
            "infoURL",
            "expires",
            "by_all_limit",
            "by_brand_limit",
            "by_user_limit",
            "by_user_wait",
            "keyword"
        ]
    }
}

Add

PropertyValue
methodPOST
inputs required["name","description","amount","holder_id"]
inputs optional["imageURL","infoURL","expires","by_all_limit","by_brand_limit","by_user_limit","by_user_wait","keyword"]

admin-promos-add-0

var currResource = {
    "@id": "/brand/104/promos"
};

api.submit(currResource, 'add', {
    "name": "product promo {hex}",
    "description": "a brand 104 promo {hex}",
    "amount": 5.43,
    "holder_id": 41
}, successFxn, errorFxn);

Example: should allow a brand member to add a promo specification

Status 200

{
    "name": "product promo {hex}",
    "description": "a brand 104 promo {hex}",
    "amount": 5.43,
    "promo_id": 3,
    "relay": {
        "amount_min": 5.43,
        "amount_max": 5.43,
        "txntype": "pn",
        "secret": "48c4",
        "by_all_limit": 25,
        "by_brand_limit": 5,
        "by_user_limit": 2,
        "by_user_wait": 24,
        "relay_id": 5
    },
    "relay_id": 5
}

admin-promos-add-1

var currResource = {
    "@id": "/brand/105/promos"
};

api.submit(currResource, 'add', {
    "name": "product promo {hex}",
    "description": "a brand 105 promo {hex}",
    "amount": 3.45
}, successFxn, errorFxn);

Example: should NOT allow a non-brand member to add a promo specification

Status 403

{
    "@context": "/api/ref/context.php",
    "error": "The requester is not a member of brand #105.",
    "hints": [

    ],
    "@graph": [

    ],
    "requestURI": "/brand/105/promos"
}

admin-promos-add-2

var currResource = {
    "@id": "/promo/collection"
};

api.submit(currResource, 'add', {
    "name": "product promo {hex}",
    "description": "a brand 104 promo {hex}",
    "amount": 5.43,
    "holder_id": 41
}, successFxn, errorFxn);

Example: should allow a brand member to add using the promo/collection endpoint

Status 200

{
    "name": "product promo {hex}",
    "description": "a brand 104 promo {hex}",
    "amount": 5.43,
    "promo_id": 4,
    "relay": {
        "amount_min": 5.43,
        "amount_max": 5.43,
        "txntype": "pn",
        "secret": "8fdc",
        "by_all_limit": 25,
        "by_brand_limit": 5,
        "by_user_limit": 2,
        "by_user_wait": 24,
        "relay_id": 6
    },
    "relay_id": 6
}

admin-promo


api.loadConcept('admin-promo');

Status 200

[
    {
        "id": 1,
        "name": "{hex}",
        "description": "A brand #104 promo",
        "amount": 8.97,
        "imageURL": null,
        "infoURL": "http://tatag.dev/ad/1",
        "created": "2014-12-31 16:00:00",
        "updated": "2016-02-16 21:33:21",
        "expires": null,
        "keyword": "software",
        "brand": "/brand/104",
        "relay": "/relay/1",
        "@id": "/promo/1",
        "@type": "promo",
        "payURL": "http://tatag.dev/for/software-1",
        "code": "software-1",
        "promoPage": "http://tatag.dev/ad/1",
        "edit": "/form/promo-edit"
    }
]

A brand promo that is administered by the current user. A promo is intended to announce or advertise products, services, and projects that any user could help pay for.

PropertyTypeDescription
@idstring...
@typestring...
amountdoubleA numeric value that quantifies an important aspect of a resource. For example, in the context of a promo or transaction record, the amount may be a product price or a suggested donation amount.
codestringAn alpha-numeric string that a payment recipient shares with a payor to authorize a payment or promo use.
createdstringThe date and time when a resource was created, in the form of `YYYY-MM-DD hh:mm:ss`.
descriptionstring...
expiresNULLThe date after which a given resource will no longer be available. For example, a promo may expire after a week.
idintegerA numeric identifier for a resource, that is unique for a given resource type.
imageURLNULLIf given, a user interface provider may use this link to display a brand icon or promo image.
infoURLstringExternal web page about a resource.
keywordstringIn the context of a relay, this is the prefix to be used with a relay id, such as the 'food-' in the relay token value of 'food-645'. This keyword is assigned by the user when creating a promo, and also helps to counter (but not prevent) spammy transaction offers by making it harder to guess the full value of a relay token.
namestringThe name of the resource.
payURLstringA URL that, when clicked, is intended to automatically open the tatag.cc wallet of a payor.
promoPagestringThe tatag.cc-hosted web page about the promo. An infoURL, when available, should be preferred as an external link.
updatedstringThe UNIX timestamp when a resource was last updated.
Links
brandlinkThe currency issuer related to this resource.
relaylinkA token that is used to preauthorize the use of a recipient account.
Forms
editformA form for updating a resource.

admin-promo-edit


api.loadId(currResource['edit']).then(...);

Status 200

// the response returned by promise.then
{
    "title": "Edit",
    "@type": "form",
    "@id": "/form/promo-edit",
    "method": "POST",
    "inputs": {
        "required": [

        ],
        "optional": [
            "name",
            "description",
            "amount",
            "imageURL",
            "infoURL",
            "expires",
            "keyword"
        ]
    }
}

Edit

PropertyValue
methodPOST
inputs required[]
inputs optional["name","description","amount","imageURL","infoURL","expires","keyword"]

admin-promo-edit-0

var currResource = {
    "@id": "/promo/1"
};

api.submit(currResource, 'edit', {
    "name": "{hex}",
    "amount": 8.97
}, successFxn, errorFxn);

Example: should allow a brand admin to edit a promo specification

Status 200

{
    "name": "{hex}",
    "amount": 8.97
}

admin-promo-edit-1

var currResource = {
    "@id": "/promo/2"
};

api.submit(currResource, 'edit', {
    "name": "{hex}",
    "amount": 7.98
}, successFxn, errorFxn);

Example: should NOT allow a non-brand admin to edit a promo specification

Status 403

{
    "@context": "/api/ref/context.php",
    "error": "The user is not a member of the brand that owns this promo and does not have accees to its details.",
    "hints": [

    ],
    "@graph": [

    ],
    "requestURI": "/promo/2"
}

admin-throttles


api.loadConcept('admin-throttles');

Status 200

{
    "brand_id": 104,
    "@type": "budgetThrottles",
    "@id": "/budget/104/throttles",
    "collectionOf": "throttle",
    "add": "/form/throttle-add",
    "throttle": [
        "/throttle/1",
        "/throttle/2",
        "/throttle/3"
    ]
}

A collection of admin-throttle.

PropertyTypeDescription
@idstring...
@typestring...
brand_idinteger(deprecated)
collectionOfstringThe term used for the collection item. For example, instead of promos.items, you could use promos.promo or promos[promos.collectionOf].
Links
throttlelinkA limit on how much an account may be used for transactions for a given period, specified as amount per brand, amount per user, and amount by all.
Forms
addformA form for adding a resource to a collection, or for adding to a resource's tracked quantity.

admin-throttles-add


api.loadId(currResource['add']).then(...);

Status 200

// the response returned by promise.then
{
    "title": "Add an inflow throttle",
    "@type": "form",
    "@id": "/form/throttle-add",
    "method": "POST",
    "inputs": {
        "required": [
            "period",
            "by_all",
            "by_brand",
            "by_user"
        ],
        "optional": [

        ]
    }
}

Add an inflow throttle

PropertyValue
methodPOST
inputs required["period","by_all","by_brand","by_user"]
inputs optional[]

admin-throttles-add-0

var currResource = {
    "@id": "/budget/104/throttles"
};

api.submit(currResource, 'add', {
    "period": 360000,
    "by_all": 100,
    "by_brand": 20,
    "by_user": 2
}, successFxn, errorFxn);

Example: should allow an admin to add a new throttle

Status 200

{
    "brand_id": 104,
    "@type": "budgetThrottles",
    "@id": "/budget/104/throttles",
    "collectionOf": "throttle",
    "period": 360000,
    "by_all": 100,
    "by_brand": 20,
    "by_user": 2,
    "throttle_id": 4,
    "created": "2016-01-21 00:14:12",
    "updated": null,
    "ended": null,
    "productURL": null
}

admin-throttles-add-1

var currResource = {
    "@id": "/budget/105/throttles"
};

api.submit(currResource, 'add', {
    "period": 360000,
    "by_all": 100,
    "by_brand": 20,
    "by_user": 2
}, successFxn, errorFxn);

Example: should NOT allow a non-admin to add a throttle

Status 403

{
    "@context": "/api/ref/context.php",
    "error": "Only brand #105 admins can add throttling specifications.",
    "hints": [

    ],
    "@graph": [

    ],
    "requestURI": "/budget/105/throttles"
}

admin-throttle


api.loadConcept('admin-throttle');

Status 200

[
    {
        "id": 1,
        "period": 172800,
        "by_all": 100,
        "by_brand": 20,
        "by_user": 2,
        "created": "2015-02-24 02:48:00",
        "updated": null,
        "ended": null,
        "productURL": null,
        "@id": "/throttle/1",
        "edit": "/form/admin-throttle-edit",
        "brand": "/brand/104"
    }
]

A set of periodic limits imposed on inflows or outflows from an administered account.

PropertyTypeDescription
@idstring...
by_allinteger...
by_brandinteger...
by_userinteger...
createdstringThe date and time when a resource was created, in the form of `YYYY-MM-DD hh:mm:ss`.
endedNULLThe date of resource or relation deactivation, formatted as `YYYY-MM-DD hh:mm:ss`.
idintegerA numeric identifier for a resource, that is unique for a given resource type.
periodintegerThe time period that applies to a resource.
productURLNULL...
updatedNULLThe UNIX timestamp when a resource was last updated.
Links
brandlinkThe currency issuer related to this resource.
Forms
editformA form for updating a resource.

admin-throttle-edit


api.loadId(currResource['edit']).then(...);

Status 200

// the response returned by promise.then
{
    "title": "Edit",
    "@type": "form",
    "@id": "/form/admin-throttle-edit",
    "method": "POST",
    "inputs": {
        "required": [

        ],
        "optional": [
            "period",
            "by_all",
            "by_brand",
            "by_user"
        ]
    }
}

Edit

PropertyValue
methodPOST
inputs required[]
inputs optional["period","by_all","by_brand","by_user"]

admin-throttle-edit-0

var currResource = {
    "@id": "/throttle/1"
};

api.submit(currResource, 'edit', {
    "period": 99999999
}, successFxn, errorFxn);

Example: should allow an admin to edit a throttle's specifications

Status 200

{
    "period": 99999999
}

Developer Resources

These are application-related resources that belongs to a developer. The consumer id and secret are required fro authentication.

dev-app


api.loadConcept('dev-app');

Status 200

[
    {
        "@id": "/app/trial",
        "@type": "appDetail",
        "budgetlog": {
            "pageOrder": "desc",
            "itemsLimit": 1000,
            "collectionOf": "data",
            "pageOf": "/report/addUse",
            "@id": "/report/addUse",
            "@type": "dataset",
            "data": [

            ]
        },
        "tally": "/tally/",
        "addedByWeek": "/added/byWeek",
        "inflowByWeek": "/inflow/byWeek",
        "outflowByWeek": "/outflow/byWeek",
        "intrauseByWeek": "/intrause/byWeek",
        "flowMatrix": "/flow/matrix",
        "advise": "/app/4/advise?from_brand=104&to_brand=105",
        "config": {
            "id": 0,
            "@id": "/app/0/config",
            "@type": "appConfig",
            "maxBalDiff": -1000,
            "maxNPratio": 0.5,
            "maxIOratio": 0.5,
            "edit": "/form/app-config-edit"
        }
    }
]

blah blah blah

PropertyTypeDescription
@idstring...
@typestring...
Links
addedByWeeklink...
adviselink...
budgetloglink...
configlink...
flowMatrixlink...
inflowByWeeklink...
intrauseByWeeklink...
outflowByWeeklink...
tallylinkPeriodic aggregated budget activity information, by brand and type of activity.

dev-budgetlog


api.loadConcept('dev-budgetlog');

Status 200

{
    "pageOrder": "desc",
    "itemsLimit": 1000,
    "collectionOf": "data",
    "pageOf": "/report/addUse",
    "@id": "/report/addUse",
    "@type": "dataset",
    "data": [
        {
            "report_id": 71,
            "txntype": "pn",
            "from_brand": 116,
            "to_brand": 114,
            "amount": 3,
            "updated": 1454357178,
            "keyword": null,
            "status": 7
        },
        {
            "report_id": 70,
            "txntype": "pn",
            "from_brand": 116,
            "to_brand": 111,
            "amount": 2,
            "updated": 1454961251,
            "keyword": null,
            "status": 7
        },
        {
            "report_id": 69,
            "txntype": "pn",
            "from_brand": 116,
            "to_brand": 110,
            "amount": 1,
            "updated": 1454961867,
            "keyword": null,
            "status": 7
        }
    ]
}

A simple log of budget additions and use as the corresponding transaction records get approved. The budgetlog may be used for data warehousing purposes.

PropertyTypeDescription
@idstring...
@typestring...
collectionOfstringThe term used for the collection item. For example, instead of promos.items, you could use promos.promo or promos[promos.collectionOf].
dataarray...
itemsLimitintegerThe maximum number of items that is returned in a collection page. To request more than the itemsLimit, make subsequent requests using the collection's 'next' or 'prev' link.
pageOfstringThe '@id' of the collection to which the current page belongs. In other words, this is the link to the default collection resource without pagination.
pageOrderstringEither 'asc' or 'desc' based on item id's.

dev-tally


api.loadConcept('dev-tally');

Status 200

{

}

Combined datasets, made of dev-addedByWeek, dev-inflowByWeek, dev-outflowByWeek, dev-intrauseByWeek, dev-flowMatrix.

PropertyTypeDescription

dev-addedByWeek


api.loadConcept('dev-addedByWeek');

Status 200

{
    "@id": "/added/byWeek?db=tatagtestdtd",
    "data": [
        {
            "brand_id": 104,
            "added": [
                {
                    "week": null,
                    "brand": 104,
                    "amount": 1000
                },
                {
                    "week": 5,
                    "brand": 104,
                    "amount": 200
                },
                {
                    "week": 47,
                    "brand": 104,
                    "amount": 500.11
                },
                {
                    "brand": 104,
                    "week": 0,
                    "amount": 0
                },
                {
                    "brand": 104,
                    "week": 1,
                    "amount": 0
                },
                {
                    "brand": 104,
                    "week": 2,
                    "amount": 0
                },
                {
                    "brand": 104,
                    "week": 3,
                    "amount": 0
                },
                {
                    "brand": 104,
                    "week": 4,
                    "amount": 0
                },
                {
                    "brand": 104,
                    "week": 6,
                    "amount": 0
                },
                {
                    "brand": 104,
                    "week": 7,
                    "amount": 0
                },
                {
                    "brand": 104,
                    "week": 8,
                    "amount": 0
                },
                {
                    "brand": 104,
                    "week": 9,
                    "amount": 0
                },
                {
                    "brand": 104,
                    "week": 10,
                    "amount": 0
                },
                {
                    "brand": 104,
                    "week": 11,
                    "amount": 0
                },
                {
                    "brand": 104,
                    "week": 12,
                    "amount": 0
                },
                {
                    "brand": 104,
                    "week": 13,
                    "amount": 0
                },
                {
                    "brand": 104,
                    "week": 14,
                    "amount": 0
                },
                {
                    "brand": 104,
                    "week": 15,
                    "amount": 0
                },
                {
                    "brand": 104,
                    "week": 16,
                    "amount": 0
                },
                {
                    "brand": 104,
                    "week": 17,
                    "amount": 0
                },
                {
                    "brand": 104,
                    "week": 18,
                    "amount": 0
                },
                {
                    "brand": 104,
                    "week": 19,
                    "amount": 0
                },
                {
                    "brand": 104,
                    "week": 20,
                    "amount": 0
                },
                {
                    "brand": 104,
                    "week": 21,
                    "amount": 0
                },
                {
                    "brand": 104,
                    "week": 22,
                    "amount": 0
                },
                {
                    "brand": 104,
                    "week": 23,
                    "amount": 0
                },
                {
                    "brand": 104,
                    "week": 24,
                    "amount": 0
                },
                {
                    "brand": 104,
                    "week": 25,
                    "amount": 0
                },
                {
                    "brand": 104,
                    "week": 26,
                    "amount": 0
                },
                {
                    "brand": 104,
                    "week": 27,
                    "amount": 0
                },
                {
                    "brand": 104,
                    "week": 28,
                    "amount": 0
                },
                {
                    "brand": 104,
                    "week": 29,
                    "amount": 0
                },
                {
                    "brand": 104,
                    "week": 30,
                    "amount": 0
                },
                {
                    "brand": 104,
                    "week": 31,
                    "amount": 0
                },
                {
                    "brand": 104,
                    "week": 32,
                    "amount": 0
                },
                {
                    "brand": 104,
                    "week": 33,
                    "amount": 0
                },
                {
                    "brand": 104,
                    "week": 34,
                    "amount": 0
                },
                {
                    "brand": 104,
                    "week": 35,
                    "amount": 0
                },
                {
                    "brand": 104,
                    "week": 36,
                    "amount": 0
                },
                {
                    "brand": 104,
                    "week": 37,
                    "amount": 0
                },
                {
                    "brand": 104,
                    "week": 38,
                    "amount": 0
                },
                {
                    "brand": 104,
                    "week": 39,
                    "amount": 0
                },
                {
                    "brand": 104,
                    "week": 40,
                    "amount": 0
                },
                {
                    "brand": 104,
                    "week": 41,
                    "amount": 0
                },
                {
                    "brand": 104,
                    "week": 42,
                    "amount": 0
                },
                {
                    "brand": 104,
                    "week": 43,
                    "amount": 0
                },
                {
                    "brand": 104,
                    "week": 44,
                    "amount": 0
                },
                {
                    "brand": 104,
                    "week": 45,
                    "amount": 0
                },
                {
                    "brand": 104,
                    "week": 46,
                    "amount": 0
                }
            ]
        },
        {
            "brand_id": 105,
            "added": [
                {
                    "week": null,
                    "brand": 105,
                    "amount": 1000
                },
                {
                    "brand": 105,
                    "week": 0,
                    "amount": 0
                },
                {
                    "brand": 105,
                    "week": 1,
                    "amount": 0
                },
                {
                    "brand": 105,
                    "week": 2,
                    "amount": 0
                },
                {
                    "brand": 105,
                    "week": 3,
                    "amount": 0
                },
                {
                    "brand": 105,
                    "week": 4,
                    "amount": 0
                },
                {
                    "brand": 105,
                    "week": 5,
                    "amount": 0
                },
                {
                    "brand": 105,
                    "week": 6,
                    "amount": 0
                },
                {
                    "brand": 105,
                    "week": 7,
                    "amount": 0
                },
                {
                    "brand": 105,
                    "week": 8,
                    "amount": 0
                },
                {
                    "brand": 105,
                    "week": 9,
                    "amount": 0
                },
                {
                    "brand": 105,
                    "week": 10,
                    "amount": 0
                },
                {
                    "brand": 105,
                    "week": 11,
                    "amount": 0
                },
                {
                    "brand": 105,
                    "week": 12,
                    "amount": 0
                },
                {
                    "brand": 105,
                    "week": 13,
                    "amount": 0
                },
                {
                    "brand": 105,
                    "week": 14,
                    "amount": 0
                },
                {
                    "brand": 105,
                    "week": 15,
                    "amount": 0
                },
                {
                    "brand": 105,
                    "week": 16,
                    "amount": 0
                },
                {
                    "brand": 105,
                    "week": 17,
                    "amount": 0
                },
                {
                    "brand": 105,
                    "week": 18,
                    "amount": 0
                },
                {
                    "brand": 105,
                    "week": 19,
                    "amount": 0
                },
                {
                    "brand": 105,
                    "week": 20,
                    "amount": 0
                },
                {
                    "brand": 105,
                    "week": 21,
                    "amount": 0
                },
                {
                    "brand": 105,
                    "week": 22,
                    "amount": 0
                },
                {
                    "brand": 105,
                    "week": 23,
                    "amount": 0
                },
                {
                    "brand": 105,
                    "week": 24,
                    "amount": 0
                },
                {
                    "brand": 105,
                    "week": 25,
                    "amount": 0
                },
                {
                    "brand": 105,
                    "week": 26,
                    "amount": 0
                },
                {
                    "brand": 105,
                    "week": 27,
                    "amount": 0
                },
                {
                    "brand": 105,
                    "week": 28,
                    "amount": 0
                },
                {
                    "brand": 105,
                    "week": 29,
                    "amount": 0
                },
                {
                    "brand": 105,
                    "week": 30,
                    "amount": 0
                },
                {
                    "brand": 105,
                    "week": 31,
                    "amount": 0
                },
                {
                    "brand": 105,
                    "week": 32,
                    "amount": 0
                },
                {
                    "brand": 105,
                    "week": 33,
                    "amount": 0
                },
                {
                    "brand": 105,
                    "week": 34,
                    "amount": 0
                },
                {
                    "brand": 105,
                    "week": 35,
                    "amount": 0
                },
                {
                    "brand": 105,
                    "week": 36,
                    "amount": 0
                },
                {
                    "brand": 105,
                    "week": 37,
                    "amount": 0
                },
                {
                    "brand": 105,
                    "week": 38,
                    "amount": 0
                },
                {
                    "brand": 105,
                    "week": 39,
                    "amount": 0
                },
                {
                    "brand": 105,
                    "week": 40,
                    "amount": 0
                },
                {
                    "brand": 105,
                    "week": 41,
                    "amount": 0
                },
                {
                    "brand": 105,
                    "week": 42,
                    "amount": 0
                },
                {
                    "brand": 105,
                    "week": 43,
                    "amount": 0
                },
                {
                    "brand": 105,
                    "week": 44,
                    "amount": 0
                },
                {
                    "brand": 105,
                    "week": 45,
                    "amount": 0
                },
                {
                    "brand": 105,
                    "week": 46,
                    "amount": 0
                },
                {
                    "brand": 105,
                    "week": 47,
                    "amount": 0
                }
            ]
        }
    ]
}

A dataset of added budgets by brand by week.

PropertyTypeDescription
@idstring...
dataarray...

dev-inflowByWeek


api.loadConcept('dev-inflowByWeek');

Status 200

{
    "@id": "/inflow/byWeek?db=tatagtestdtd",
    "data": [
        {
            "brand_id": 104,
            "inflow": [
                {
                    "week": 47,
                    "brand": 104,
                    "amount": 9.37
                }
            ]
        }
    ]
}

A dataset of inflow, a.k.a. received budget use, by brand by week.

PropertyTypeDescription
@idstring...
dataarray...

dev-outflowByWeek


api.loadConcept('dev-outflowByWeek');

Status 200

{
    "@id": "/outflow/byWeek?db=tatagtestdtd",
    "data": [
        {
            "brand_id": 105,
            "outflow": [
                {
                    "week": 47,
                    "brand": 105,
                    "amount": 9.37
                }
            ]
        }
    ]
}

A dataset of outflow, a.k.a. originated budget use, by brand by week.

PropertyTypeDescription
@idstring...
dataarray...

dev-intrauseByWeek


api.loadConcept('dev-intrauseByWeek');

Status 200

{
    "@id": "/intrause/byWeek?db=tatagtestdtd",
    "data": [
        {
            "brand_id": 104,
            "intrause": [
                {
                    "week": 47,
                    "brand": 104,
                    "amount": 90.76
                }
            ]
        }
    ]
}

A dataset of intrause, a.k.a intra-entity budget use, by brand by week.

PropertyTypeDescription
@idstring...
dataarray...

dev-flowMatrix


api.loadConcept('dev-flowMatrix');

Status 200

{
    "@id": "/flow/matrix?db=tatagtestdtd",
    "brands": [

    ],
    "matrix": [

    ]
}

A dataset of budget use between brands by week.

PropertyTypeDescription
@idstring...
matrixarray...
Links
brandslink...

dev-details


api.loadConcept('dev-details');

Status 200

[
    {
        "@id": "/app/trial",
        "@type": "appDetail",
        "budgetlog": {
            "pageOrder": "desc",
            "itemsLimit": 1000,
            "collectionOf": "data",
            "pageOf": "/report/addUse",
            "@id": "/report/addUse",
            "@type": "dataset",
            "data": [

            ]
        },
        "tally": "/tally/",
        "addedByWeek": "/added/byWeek",
        "inflowByWeek": "/inflow/byWeek",
        "outflowByWeek": "/outflow/byWeek",
        "intrauseByWeek": "/intrause/byWeek",
        "flowMatrix": "/flow/matrix",
        "advise": "/app/4/advise?from_brand=104&to_brand=105",
        "config": {
            "id": 0,
            "@id": "/app/0/config",
            "@type": "appConfig",
            "maxBalDiff": -1000,
            "maxNPratio": 0.5,
            "maxIOratio": 0.5,
            "edit": "/form/app-config-edit"
        }
    }
]

An application's basic details.

PropertyTypeDescription
@idstring...
@typestring...
Links
addedByWeeklink...
adviselink...
budgetloglink...
configlink...
flowMatrixlink...
inflowByWeeklink...
intrauseByWeeklink...
outflowByWeeklink...
tallylinkPeriodic aggregated budget activity information, by brand and type of activity.
Forms
editformA form for updating a resource.

dev-advise


api.loadConcept('dev-advise');

Status 200

{
    "from_brand": 104,
    "to_brand": 105,
    "consumer_id": 4,
    "@id": "/app/4/advise",
    "@type": "appAdvise",
    "advisor": 4,
    "advise": {
        "status": 7
    }
}

An application's advise on whether to accept or reject a payment offer.

PropertyTypeDescription
@idstring...
@typestring...
advisorinteger...
consumer_idinteger...
from_brandinteger...
to_brandinteger...
Links
adviselink...

dev-config


api.loadConcept('dev-config');

Status 200

{
    "id": 0,
    "@id": "/app/0/config",
    "@type": "appConfig",
    "maxBalDiff": -1000,
    "maxNPratio": 0.5,
    "maxIOratio": 0.5,
    "edit": "/form/app-config-edit"
}

An application's optional configuration settings, primarily intended for advisor-type apps.

PropertyTypeDescription
@idstring...
@typestring...
idintegerA numeric identifier for a resource, that is unique for a given resource type.
maxBalDiffinteger...
maxIOratiodouble...
maxNPratiodouble...
Forms
editformA form for updating a resource.

dev-config-edit


api.loadId(currResource['edit']).then(...);

Status 200

// the response returned by promise.then
{
    "title": "Edit an application configuration.",
    "@type": "form",
    "@id": "/form/app-config-edit",
    "method": "POST",
    "inputs": {
        "required": [

        ],
        "optional": [

        ]
    }
}

Edit an application configuration.

PropertyValue
methodPOST
inputs required[]
inputs optional[]

dev-config-edit-0

var currResource = {
    "@id": "/app/4/config"
};

api.submit(currResource, 'edit', {
    "minRevBal": -5
}, successFxn, errorFxn);

Example: should allow an application owner to edit advise configuration

Status 200

{
    "minRevBal": -5
}

System Resources

These are system administration related resources.

sys-trigger


api.loadConcept('sys-trigger');

Status 200

{
    "@id": "/sys/trigger",
    "@type": "systemTrigger",
    "approve": "/cron/records",
    "add": "/cron/budgetAdd",
    "report": "/cron/report",
    "tally": "/cron/tally"
}

blah blah blah

PropertyTypeDescription
@idstring...
@typestring...
Links
reportlink...
tallylinkPeriodic aggregated budget activity information, by brand and type of activity.
Forms
addformA form for adding a resource to a collection, or for adding to a resource's tracked quantity.
approveformA form for approving the completion of a pending resource action.

sys-approve


api.loadConcept('sys-approve');

Status 200

{
    "numApproved": 0
}

blah blah blah

PropertyTypeDescription
numApprovedinteger...

sys-add


api.loadConcept('sys-add');

Status 200

{
    "@id": "/cron/budgetAdd",
    "@type": "CronAdd"
}

blah blah blah

PropertyTypeDescription
@idstring...
@typestring...

sys-report


api.loadConcept('sys-report');

Status 200

{
    "pageOrder": null,
    "itemsLimit": 50,
    "collectionOf": null,
    "pageOf": null,
    "@id": "/cron/report",
    "@type": "report",
    "numInserted": null
}

blah blah blah

PropertyTypeDescription
@idstring...
@typestring...
collectionOfNULLThe term used for the collection item. For example, instead of promos.items, you could use promos.promo or promos[promos.collectionOf].
itemsLimitintegerThe maximum number of items that is returned in a collection page. To request more than the itemsLimit, make subsequent requests using the collection's 'next' or 'prev' link.
numInsertedNULL...
pageOfNULLThe '@id' of the collection to which the current page belongs. In other words, this is the link to the default collection resource without pagination.
pageOrderNULLEither 'asc' or 'desc' based on item id's.

sys-tally


api.loadConcept('sys-tally');

Status 200

{
    "@id": "/cron/tally",
    "@type": "cronTally",
    "currWeek": 4,
    "numBrands": 13,
    "totalUpdates": 2
}

blah blah blah

PropertyTypeDescription
@idstring...
@typestring...
currWeekinteger...
numBrandsinteger...
totalUpdatesinteger...