Recipient

A Recipient is a participant who receives a Document for signing, witnessing, or approval. Each Recipient plays a role (most commonly signer) and the API tracks their progress through the signing workflow — from email sent, to opened, to viewed, to signed.

Implements: Node

Fields

Field	Type	Description
id	ID!	Unique identifier
firstName	String	First name
lastName	String	Last name
email	String	Email address
phoneNumber	String	Phone number (E.164 format) for SMS
role	String	Role name on the document
roleType	ROLETYPE	SIGNER, WITNESS, or APPROVER
status	String	Current signing status
authentication	RecipientAuthentication	Auth method: EMAIL, EMAIL_SMS, NONE, UNKNOWN
timeZone	Int	Recipient's timezone
experience	ID	Experience ID used for this recipient
expiryDate	AWSDateTime	When the signing invitation expires
skipped	Boolean	Whether this recipient was skipped
nominate	Boolean	Whether this recipient nominates the next signer
detailsTBD	Boolean	Recipient details are to be determined
recipientOrder	Int	Send order for this recipient

Tracking Fields

Field	Type	Description
sentDateTime	AWSDateTime	When the invitation email was sent
emailOpenedDateTime	AWSDateTime	When the email was first opened
documentFirstViewedDateTime	AWSDateTime	When the document was first viewed
signedDateTime	AWSDateTime	When the document was signed
emailProblem	String	Description if email delivery had issues

Relationships

Field	Type	Description
document	Document	The target document
elementConnection	DocumentElementConnection	Fields this recipient may have completed
schedule	[ScheduleItem]	Reminder schedule for this recipient

Query

query GetRecipient($id: ID!) {
  recipient(id: $id) {
    id
    firstName
    lastName
    email
    status
    roleType
    signedDateTime
  }
}

Recipients are most commonly accessed as a nested field on a Document query rather than queried directly.

Example

Querying a document with full recipient details (based on the Legalesign Console app):

query GetDocumentRecipients {
  document(id: "ZG9jMWVmMjdkYWYtMGJlMS0xMWYwLWJiYjUtMDZlNDc2YTA3NTY5") {
    id
    name
    recipients {
      id
      firstName
      lastName
      email
      status
      roleType
      role
      authentication
      recipientOrder
      detailsTBD
      expiryDate
      experience
      phoneNumber
      sentDateTime
      emailOpenedDateTime
      documentFirstViewedDateTime
      signedDateTime
      emailProblem
      schedule {
        id
        utcSendTime
        subject
        when
      }
      elementConnection {
        documentElements {
          id
          elementType
          label
          value
          signer
          role
        }
      }
    }
  }
}

Related

• Document — the document this recipient is on
• How Pagination Works — recipients are a nested list, not a connection
• Query Examples — basic recipient query
• Mutation Examples — update and reset recipients
• Input Examples — recipient input structure