Organization Hierarchies

Verdocs manages access to features with pass-through fees from other vendors (such as knowledge-based authentication or KBA) via a system of "entitlements." Entitlements make it easy to track access to and usage of these kinds of features across an organization. But for customers managing clients of their own, this can be clumsy because as new organizations are created, these entitlements and usage metrics do not carry over.

Organization Hierarchies can help address this requirement. This feature is currently only available at the API level, but is easy to use. When creating an organization, you may specify that it should be considered a sub-account of your primary organization by setting a "parent_id" field in the API call:

curl -X POST https://api.verdocs.com/organizations \
    -H "Authorization: Bearer eY........." \
    -H "Content-Type: application/json" \
    -d '{"name": "New Child Org", "parent_id": "123....." }'

As shown in this example, the creation request must set the parent_id field to the ID of the parent organization, and be accompanied by an access token associated with that same parent organization. This step will establish the relationship between the two.

Listing Sub-Accounts

Two API endpoint responses are enabled by this step. First, when retrieving a detailed organization record, sub-accounts will be included in a new "children" array as a field in the response. Second, a new API endpoint may retrieve these sub-accounts directly:

curl -X GET https://api.verdocs.com/organizations/ORGID/children \
    -H "Authorization: Bearer eY........." \
    -H "Content-Type: application/json"

This will retrieve only the sub-accounts, for direct access.

Updating and Deleting Sub-Accounts

All organization-level operations work on sub-accounts as they would on any other, with two exceptions:

1. After creating the new sub-account, access credentials with ownership rights will be included in the response. Developers must use these new credentials to perform operations at the sub-account level. We recommend immediately creating an API key for the new sub-account to be used to perform subsequent requests. The access token for the parent organization is valid only for the creation request, not subsequent operations.
2. Deleting an organization is still a significant operation in the e-Signature industry because of the legal implications of discarding data that may have been related to e-signing activities. Just like with standard organizations, there is currently no automated way to delete a sub-account, but we would be happy to assist you with this. Please contact support@verdocs.com if you need to discuss an automation requirement, or just want to clean up records from development or testing efforts.

Entitlements

One of the main advantages of creating sub-accounts is entitlement management. Sub-accounts inherit entitlements from the parent organization. You can thus grant (by establishing a sub-account) or keep separate (by establishing a new top-level organization) your own organization's entitlements to a new one by selectively using this feature.

To assist with monitoring and billing purposes, we have added a new API endpoint to retrieve usage metrics for entitlements:

curl -X GET https://api.verdocs.com/organizations/ORGID/metrics \
    -H "Authorization: Bearer eY........." \
    -H "Content-Type: application/json"

NOTE: We will shortly be introducing a number of additional parameters such as date-range and org-level filtering. Please refer to our API Browser for the most up-to-date list of options that may be included in this call.

This endpoint will return aggregate usage data on a daily and monthly level to support any monitoring or pass-through billing requirements you may have.