Recipient userId in envelope differs from DocuSign account userId

Hi ​@Aung,

I hope this message finds you well.

The userId you see on envelope recipients is an envelope-level identifier; it is not guaranteed (and often not intended) to equal the Admin/Users API account userId.

Please see the answers to your questions below:

1. Recipient-specific identifier. The userId returned by Envelopes::listRecipients is the internal identifier used by Envelope Core for that recipient on that envelope; for “userless”/email-only recipients, it can even be a synthetic value derived from the recipient id, not any real account user record.

2. Matches only when the recipient truly maps to an account user. It may match an Admin/Users API userId when the recipient is an actual Docusign user membership on that account and the envelope was created using that membership (for example, a sender adding an in-account user as a signer). In general you must treat equality as “nice when it happens” rather than guaranteed behavior.

3. No impact if you follow the documented patterns.

   • For embedded signing, Docusign supports two matching strategies for CreateRecipientView:
     • Match email + userName + clientUserId, or
     • Match userId (from listRecipients) + clientUserId.
     In both cases, the userId is only required to match the envelope’s recipient, not the Admin/Users API userId, so the difference does not break embedded signing or envelope access checks.
   • Envelope viewing/permissions are enforced against the envelope’s recipient row (envelope userId/recipientId/envelopeId trio), not the Admin user record.

4. Recommended mapping strategy.

   • Do not rely on listRecipients.userId == UsersApi.userId.
   • To map an envelope recipient to a Docusign account user, use business keys such as email (and accountId), then look up the user via the Admin/Users APIs, and treat that as the canonical account identity; keep the envelope userId only as an envelope-scoped key for operations like CreateRecipientView when you choose the userId + clientUserId pattern.

For further detail, see the envelope listRecipients reference and the embedded signing deep-dive, which explicitly describes the userId + clientUserId flow:

• EnvelopeRecipients::listRecipients
• Deep dive into the embedded signing recipient view

I hope the information above is helpful.

Kind regards,
Leandro Reis - Associate Developer Support Engineer