Understanding Profiles, or "Why do my API calls return the wrong data?"

Periodically, we receive support requests from developers who believe they are receiving the wrong template/envelope data when querying lists of those records. A common source of this issue is a misunderstanding in the concept of a "Profile" within the Verdocs ecosystem.

Verdocs is a SaaS platform, with two specific challenges:

1. A human being might be a member of more than one organization. Consider the diagram below. Will Power is an employee of All Ways Fitness and does not use e-signing anywhere else. But Paige Turner is both an employee of Holden Accounting during the week and also on weekends works at All Ways Fitness as well.
2. An organization might have hierarchy. Many Verdocs customers/developers are resellers who manage their own client accounts on the platform. A single developer might therefore have access to many organizations.

There are three critical terms in this structure:

• User: A single person, regardless of their relationship with different organizations. In the diagram above, this would be Will Power or Paige Turner.
• Organization: A single entity, typically a company, which has one or more members (typically employees). Each member has different rights depending on their role, e.g. member vs. admin vs. owner. In the diagram above this would be Holden Accounting or All Ways Fitness.
• Profile: Maps a person's relationship to an organization. In the diagram above there are three profiles: Paige Turner as an Admin of Holden Accounting, Paige Turner as an Admin of All Ways Fitness, and Will Power also as an admin of All Ways Fitness.

Most users understand this structure, and this is how most SaaS platforms work. However, there can be a point of confusion for developers regarding the concept of a "current" profile. In the diagram above, the bold purple borders indicate each user's current profile - both Paige Turner and Will Power are currently working with All Ways Fitness.

In Verdocs, data is always returned for a user's current profile by default, regardless of the access token that was used to make an API call. Access tokens are checked for validity based on a number of criteria, but as long as they are valid, the token is only used to identify the person making the call. Once that is done, the "current" profile takes over and data will be retrieved/manipulated on that basis. In the diagram above, if a developer writing an app for Paige Turner requests her data, the templates and envelopes returned will be for All Ways Fitness, even if the access token used in the call was issued while Holden Accounting was current when it as generated. This is because in Web applications, users tend to remember what "mode" they are in, and it can be confusing for them if this gets overridden, e.g. Paige is working at All Ways Fitness on Saturday and suddenly seeing Holden Accounting data.

As a developer, you have three options to override this behavior:

1. Call the "Switch Profile" endpoint (POST /v2/profiles/\{profile_id\}/switch or switchProfile() in the JS SDK) prior to making any calls, to ensure the profile you wish to use is selected as "current". This is the best option if you want to stay in sync with Web/Teams/other apps so users see consistent data across all their experiences.
2. Create separate developer-only profiles in each organization that you manage for each client that you onboard. This is the recommended option for resellers who may manage/oversee many client sub-accounts, and need admin access to their data regardless of what users do themselves.
3. Override this default behavior entirely by setting the header x-ignore-current: true in API calls. If this header is set, both the profile_id and organization_id from the access token will be used rather than the current profile in the database. This option is recommended for developers that want the lowest-code option without having to track or be aware of what profile is "current" for any given API call.