Authority limits and authority limit profiles

An authority limit is a restriction placed upon a user that limits the types of transactions that user can create. It can also determine whether these new transactions require approval from someone with greater authority. An authority limit profile is a named collection of authority limits. For example, there might be an authority limit profile named "Standard Billing Clerk Profile" that has a set of authority limits appropriate for a standard billing clerk.

Users must be assigned authority limit profiles. If a user has no authority limit profile, every transaction they create requires approval.

Through Cloud API, you can retrieve information about authority limits and authority limit profiles. As of this release, there is no functionality that allows you to create, update, or delete authority limit profiles through Cloud API.

For more information on authority limits, see Requiring transaction approval.

Querying for authority limits and authority limit profiles

Use the following endpoints to query for authority limit profiles and limits.

Endpoint	Retrieves
GET `admin/v1/authority-limit-profiles`	A collection of authority limit profiles
GET `admin/v1/authority-limit-profiles/{authorityLimitProfileId}`	Details of an authority limit profile
GET `admin/v1/authority-limit-profiles/{authorityLimitProfileId}/authority-limits`	A list of limits for a specific authority profile
GET `admin/v1/authority-limit-profiles/{authorityLimitProfileId}/authority-limits/{authorityLimitId}`	Information about a specific limit in an authority limit profile

For example, the following request retrieves information about authority limit profile default_data:2.

Command

GET /admin/v1/authority-limit-profiles/default_data:2

Response

{
    "data": {
        "attributes": {
            "description": "General default authority",
            "id": "default_data:2",
            "name": "General"
        },
        "checksum": "0",
        "links": {
            "authority-limits": {
                "href": "/admin/v1/authority-limit-profiles/default_data:2/authority-limits",
                "methods": [
                    "get"
                ]
            },
            "self": {
                "href": "/admin/v1/authority-limit-profiles/default_data:2",
                "methods": [
                    "get"
                ]
            }
        }
    }
}

You can query for specific authority limits or retrieve a list of all authority limits in an authority limit profile. The information provided for each authority limit is the same whether you query for one or all the authority limits.

The following retrieves information about the authority limits in authority limit profile default_data:2

Command

GET /admin/v1/authority-limit-profiles/default_data:2/authority-limits

Response

{
    "count": 25,
    "data": [
        {
            "attributes": {
                "id": "bc:ShlFtMFFN8BjwuA1BWvln",
                "limitAmount": {
                    "amount": "1000000.00",
                    "currency": "usd"
                },
                "limitType": {
                    "code": "advancecommission",
                    "name": "Advance Commission"
                }
            },
            ...
        },
        {
            "attributes": {
                "id": "bc:SAkcsI2tqo0gFzFOI6yFG",
                "limitAmount": {
                    "amount": "1000000.00",
                    "currency": "usd"
                },
                "limitType": {
                    "code": "negwtoffagbillprodunap",
                    "name": "Agency Bill Negative Writeoff From Producer Unapplied"
                }
            },
            ...
        },
        {
            "attributes": {
                "id": "bc:SqlpqJgWAJa6xjkOMCtqp",
                "limitAmount": {
                    "amount": "1000000.00",
                    "currency": "usd"
                },
                "limitType": {
                    "code": "writeoffagbillprodunap",
                    "name": "Agency Bill Writeoff From Producer Unapplied"
                }
            },
            ...
        },
        ...
    ]
}

Checking authority limits before making transactions

A common use case for the authority limit endpoints is to determine whether a user has authority to create a transaction. The authority of the user determines if the transaction will be processed immediately or will be routed to a user with approval permissions.

Differences between Cloud API and the BillingCenter user interface

In the BillingCenter user interface, users receive alerts when they attempt to create transactions that exceed their authority limits. For example, if a user attempts to create a disbursement that exceeds their disbursement authority limit, they receive an alert that the disbursement will be sent to a supervisor for approval rather than being processed immediately. The user can either choose to cancel the disbursement or submit it anyway, creating an activity for their supervisor.

These alert mechanisms appear only in the BillingCenter user interface and are not sent as part of the response in Cloud API. When a caller attempts to create a transaction that exceeds their authority limit, the request succeeds. However, the transaction is not yet created, and an approval activity is created instead. Information on the approval activity can be found in the response payload, such as the activity id and the assigned user.

The primary difference between the user interface and Cloud API is that creating these activities through Cloud API does not give users the option to cancel before making the activity. However, the caller is able to check authority limits before making transactions, so they can know if the transaction will need approval. See the instructions below to do this.

Check an authority limit

In Cloud API, you can know if a transaction will be sent for supervisor approval by comparing the user’s authority limit with the desired amount for a specific transaction. You can retrieve the necessary information with two API calls.

Before you do this, you must have

The id of the user
The amount of the desired transaction
The type of transaction

If you have this information, perform the following steps:

Get the user’s authority limit profile by calling the following endpoint:
GET /admin/v1/users/{userId}
If the user has an authority limit profile, there is an authorityLimitProfile object in the response. It contains the id of the authority limit profile.
Get the user’s authority limit for the transaction by calling the following endpoint using the id of the authority limit profile:
GET /admin/v1/authority-limit-profiles/{authorityLimitProfileId}/authority-limits
This call returns a list of authority limits for different transactions for the user. Authority limits have transaction names and codes in the limitType object and amounts in the limitAmount objects. These can be used to identify the limit for the desired transaction. You can also use a filter query parameter to retrieve only the type of transaction you are looking for, such as ?filter=limitType:eq:approvedisbursement.
Check the authority limit against the amount of the desired transaction.