Common API Tasks🐈: find your organization information
Welcome to a stupendous new episode of the CAT🐈 (Common API Tasks) blog. In this blog series I’ll be giving you all you need to complete small, specific, SDK-supported tasks using one of our APIs. You can find all articles in this series on the DocuSign developer blog.
In today’s edition I’m going to discuss the concept of an organization in the DocuSign hierarchy of objects. An organization is an optional construct that can be used to lump together one or more DocuSign accounts. It’s a useful practice for large companies to separate their DocuSign activity into multiple accounts, but still have a central mechanism to manage these accounts. Find out more about how to create an organization for your developer account by following this article on creating an organization in DocuSign Admin.
In an earlier article in this series about adding users to your account, I explained that a DocuSign user can be a member (DocuSign membership is a combination of a user and an account together) in one or more DocuSign accounts. An account, on the other hand, can only be a member of a single organization. (And an organization can have multiple accounts, which makes it a one-to-many relationship between organizations and accounts).
Here is a detailed diagram showcasing the relationship between users, accounts, members, and organizations:
DocuSign Admin API
So far, I’ve explained various types of DocuSign concepts pertaining to how DocuSign is provisioned for use by customers. Now let’s talk about how you can use one of our APIs to get this information from your application. The DocuSign Admin API is a smaller API that has endpoints related to managing organizations, accounts, and users across DocuSign. One of the most useful things you can do using this API is to obtain a list of organizations that correspond to the user whose credentials were used to authenticate and obtain a token to make an API call. As a reminder, all DocuSign API calls are authenticated and require that you obtain a proper OAuth 2.0 access token. This token is associated with a specific user (the lowest level in the diagram above), which means that when you make an API call to get the list of organizations, you may get more than one. If the user is a member of more than one account, you may get more than one organization. It’s also possible a user is not a member of any organization, and the API call will therefore return an empty set.
The DocuSign Admin API does have the same set of SDKs we have for the eSignature API, so I’m going to show small code snippets utilizing the SDKs in this blog post.
C#
// I use the developer path below; remove -d for production
var apiClient = new DocuSign.Admin.Client.ApiClient("https://api-d.docusign.net/management");
// the access token must be obtained using an OAuth 2.0 authentication flow
apiClient.Configuration.DefaultHeader.Add("Authorization", "Bearer " + accessToken);
var accountsApi = new DocuSign.Admin.Api.AccountsApi(apiClient);
var organizations = accountApis.GetOrganizations().Organizations;
// Check to see if the user is a member of least one organization
if (organizations.Any())
{
Guid? organizationId = organizations[0].Id;
}
Java
// I use the developer path below; remove -d for production
ApiClient apiClient = new new ApiClient("https://api-d.docusign.net/management");
// The access token must be obtained using an OAuth 2.0 authentication flow
apiClient.addDefaultHeader("Authorization", "Bearer " + accessToken);
AccountApi accountApi = new AccountsApi(apiClient);
java.util.List<OrganizationResponse> organizations = accountsApi.getOrganizations().getOrganizations();
// Check to see if the user is a member of least one organization
if (organizations.length > 0)
{
UUID organizationId = organizations.org[0].getId();
}
Node.js
let dsApiClient = new docusignAdmin.ApiClient();
// I use the developer path below; remove -d for production
apiClient.setBasePath('https://api-d.docusign.net/management');
// The access token must be obtained using an OAuth 2.0 authentication flow
apiClient.addDefaultHeader('Authorization', 'Bearer ' + accessToken);
let accountsApi = new docusignAdmin.AccountsApi(apiClient);
let organizations = await accountsApi.getOrganizations();
// Check to see if the user is a member of least one organization
if (organizations.length > 0)
{
let organizationId = organizations.organizations[0].id;
}
PHP
$config = new DocuSign\Admin\Configuration();
# I use the developer path below; remove -d for production
$config->setHost('https://api-d.docusign.net/management');
# The access token must be obtained using an OAuth 2.0 authentication flow
$config->addDefaultHeader('Authorization', 'Bearer ' . $access_token);
$api_client = new DocuSign\Admin\Client\ApiClient($config);
$accounts_api = new DocuSign\Admin\Api\AccountsApi($this->apiClient);
$organizations = $accounts_api->getOrganizations()['organizations'];
# Check to see if the user is a member of least one organization
if (count($organizations) > 0)
{
$organization_id = $organization[0]['id'];
}
Python
# I use the developer path below; remove -d for production
api_client = ApiClient(host='https://api-d.docusign.net/management')
# The access token must be obtained using an OAuth 2.0 authentication flow
api_client.set_default_header(
header_name='Authorization',
header_value=f'Bearer {access_token}')
accounts_api = AccountsApi(api_client)
organizations = accounts_api.get_organizations()
# Check to see if the user is a member of least one organization
if len(organizations.to_dict()) > 0:
organization_id = [0]['id']
Ruby
configuration = DocuSign_Admin::Configuration.new
# I use the developer path below; remove -d for production
configuration.host = 'https://api-d.docusign.net/management'
api_client = DocuSign_Admin::ApiClient.new(configuration)
# The access token must be obtained using an OAuth 2.0 authentication flow
api_client.set_default_header('Authorization', 'Bearer #{access_token}')
accounts_api = DocuSign_Admin::AccountsApi.new(api_client)
organizations = accounts_api.get_organizations().organizations
# Check to see if the user is a member of least one organization
if organizations.length() > 0
organization_id = [0].as_json['id']
end
That’s it for today’s edition... I hope you found it useful. If you have any questions, comments, or suggestions for topics for future Common API Tasks posts, feel free to email me. Until next time...
