Skip to navigation
Platform 101AuthenticateAuthentication reference

User info endpoint

View as Markdown

The /oauth/userinfo endpoint returns account information and the base_uri needed to interact with the Docusign platform APIs. Your integration should call this method to get the information needed to begin making API calls during setup, then store it for use in future calls.

The response data from this call should always be cached, at least for your application’s entire session. It changes very infrequently, typically only when a user is added to or removed from an account.

Note: Docusign enforces hourly limits on the number of /oauth/userinfo requests per user ID and per integration key. See User info endpoint limits for details.

The Docusign authentication service resides on a different subdomain than the core API service:

  • https://account-d.docusign.com for the developer environment
  • https://account.docusign.com for the live production system

This endpoint requires only a valid access token to call and has no other parameters. Its call syntax is:

GET https://account-d.docusign.com/oauth/userinfo

A successful call will return a 200 OK response containing a userInfo object.

A typical response with organizationInfo for one of the user’s accounts looks like:

{
  "sub": "4799e5e9-xxxx-xxxx-xxxx-cf4713bbcacc",
  "name": "First Last",
  "given_name": "First",
  "family_name": "Last",
  "created": "2015-08-13T22:03:03.45",
  "email": "first.last@example.com",
  "accounts": [
    {
      "account_id": "a4ec37d6-xxxx-xxxx-xxxx-143885c333aa",
      "is_default": false,
      "account_name": "Example Europe Ltd",
      "base_uri": "https://eu.docusign.net"
    },
    {
      "account_id": "a4ec37d6-xxxx-xxxx-xxxx-143885c220e1",
      "is_default": true,
      "account_name": "Example Corporation",
      "base_uri": "https://na3.docusign.net",
      "organization": {
        "organization_id": "9c5fb8e1-xxxx-xxxx-xxxx-054ff8a249bf",
        "links": [
          {
            "rel": "self",
            "href": "https://account.domain.example.com/organizations/9c5fb8e1-xxxx-xxxx-xxxx-054ff8a249bf"
          }
        ]
      }
    }
  ]
}
NameTypeDescription
substringThe GUID user ID of the logged in user.
namestringThe name of the account holder.
given_namestringThe given name of the account holder.
family_namestringThe family name of the account holder.
createdstringThe ISO 8601:2004 DateTime when the account was created.
emailstringThe email address of the account holder.
accountsaccountInfoAn array of accountInfo objects holding data on the individual accounts (minimum 1) associated with the user. Each user may be part of multiple accounts.

Note: Typically, exactly one of the returned accountInfo entries will have its is_default property set to true, while the others will be false. In some rare error cases, the accounts attribute will have zero entries, or no entry will have is_default set to true. If this occurs, contact Docusign customer support to have the user’s records updated and repaired.
account_idstringThe GUID identifying the account. Part of the accountInfo object.
is_defaultbooleanIf true, this account is the account holder’s default account. Part of the accountInfo object.
account_namestringThe name associated with this account. Part of the accountInfo object.
base_uristringThe base URI that is used for making API calls on behalf of this account. Part of the accountInfo object.
organizationorganizationInfoHolds data on the organization to which this account belongs. Part of the accountInfo object.
organization_idstringThe GUID identifying the organization to which this account belongs. Part of the organizationInfo object.
linksorgLinkInfoAn array of orgLinkInfo objects.
relstringself indicates that the href link is for the current user.
hrefstringA URL for logging into the account server for this organization.

The accounts node in the response is an array of account information entries. It is not uncommon for a user to be a member of multiple accounts. At setup/configuration, have the administrator provide the desired Docusign account ID and the administrator’s user ID. After retrieving the array of accountInfo objects, find the matching account ID. Store the related base_uri for constructing the API URL.

For loosely coupled integration services, it may be preferable to use the accountInfo objects to construct a list and ask the user to pick the account. The authenticated user’s default account has the is_default property set to true.

Note: This API method supports the CORS standard, so it can be called from applications that run in browsers, including React and similar browser-based application frameworks. No setup or configuration is needed to enable the API method’s CORS support.

Form your base path

With an account selected, concatenate its base_uri and account_id fields to create the full path you will use to make REST API requests. The latest REST API version is v2.1:

{base_uri} + "/restapi/v2.1/accounts/" + {account_id}

For example, using the response data above, the base path for the developer environment would be:

https://demo.docusign.net/restapi/v2.1/accounts/fe0b61a3-xxxx-xxxx-xxxx-4592af32aa9b/

With a base path formed, you can start making requests to the core Docusign API service by appending URIs to your base path. For example, to create an envelope in the developer environment, you could make the following request:

Authorization: Bearer eyJ0eX...MrhIddzBAQ
POST https://demo.docusign.net/restapi/v2.1/accounts/fe0b61a3-xxxx-xxxx-xxxx-4592af32aa9b/envelopes
{
  "status": "sent",
  "emailSubject": "Sent from the Docusign REST API",
  "documents": [
    {
      "documentId": "1",
      "name": "contract.pdf",
      "documentBase64": "base64 document bytes...",
    }
  ],
  "recipients": {
    "signers": [
      {
        "email": "jane.dough@example.com",
        "name": "Jane Dough",
        "recipientId": "1",
        "routingOrder": "1",
      }
    ]
  }
}

Next steps