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#

Java

Node.js

PHP

Python

Ruby

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...

Additional resources