Skip to main content

Troubleshoot Send Validation

The send pipeline validates its input before document creation begins. If validation fails, the mutation returns the error straight back to the client and no task ID is returned.

This applies to:

Copy For Your AI​

Use this when prompting an AI tool to help with Legalesign GraphQL send workflows:

Use the Legalesign GraphQL send validation rules below as the source of truth.

- Treat send input as strictly validated JSON.
- If send input is invalid, the mutation returns an error immediately and no task ID is returned.
- Only poll task after send succeeds and returns a task ID.
- For send workflows, monitor task.report.status until it reaches COMPLETED or FAILED.
- Prefer subscriptions over polling for production real-time UX.
- groupId, templateId, title, and recipients are required.
- Base64 IDs must decode to the expected prefixes:
  groupId=grp, templateId=tpl, roleId=rol, scheduleId=sch, experience=exp, field id=ele, attachment id=att.
- recipients must contain fewer than 200 items.
- Each recipient must include email and order.
- The input must include an initial recipient: either order 0, or order 1 when roleId is provided.
- The recipient with the lowest order number must have a non-empty email.
- title must be 1028 characters or fewer.
- tag must be 250 characters or fewer.
- pdfPassword must be 150 characters or fewer.
- documentCCEmail must contain 10 email addresses or fewer.
- redirect must be a valid URI or null.

If the AI needs fuller guidance, point it to this page.

AI Summary​

  • Treat send input as strict JSON with validation rules.
  • If send input is invalid, the mutation returns an error immediately and no task ID is returned.
  • Only poll task after send succeeds and returns a task ID.
  • For send workflows, monitor task.report.status until it reaches COMPLETED or FAILED.
  • For production real-time UX, prefer subscriptions over polling.

How to Detect a Validation Failure​

Run the mutation as normal.

  • If the input is invalid, the mutation returns a validation error immediately.
  • If the input is valid, the mutation returns a task ID and document creation continues asynchronously.

That means validation troubleshooting happens at mutation time, not via the task query.

Only start polling task after send has succeeded and returned a task ID.

What Kind of Errors You Can Expect​

The send validator checks the shape and contents of the input JSON before processing continues. Validation failures are specific to the field that failed, for example:

  • send input missing required field 'groupId'
  • send input.groupId must be a base64-encoded group id
  • send input.recipients must include a recipient with order 0, or order 1 when roleId is provided
  • recipients[0].email must be a valid email
  • recipients[1].attachments[0] must be a base64-encoded attachment id

Common Validation Problems​

Missing required top-level fields​

These fields are required:

  • groupId
  • templateId
  • title
  • recipients

Invalid encoded IDs​

The validator checks that IDs are base64-encoded and have the expected decoded prefix:

  • groupId -> grp
  • templateId -> tpl
  • roleId -> rol
  • scheduleId -> sch
  • experience -> exp
  • field id -> ele
  • attachment id -> att

Recipient ordering problems​

The send input must include an initial recipient:

  • either a recipient with order: 0
  • or a recipient with order: 1 when roleId is provided

Also, the recipient with the lowest order number must have a non-empty email.

Recipient field limits​

Common recipient validation rules include:

  • email must be valid and 75 characters or fewer
  • firstName and lastName must be 60 characters or fewer
  • phoneNumber must be 120 characters or fewer
  • message must be 10000 characters or fewer
  • expiryDate must be a valid ISO 8601 datetime or null
  • ccEmail must be a valid email
  • ccIncludeLink must be a boolean

Top-level field limits​

Common send-level validation rules include:

  • title must be 1028 characters or fewer
  • tag must be 250 characters or fewer
  • pdfPassword must be 150 characters or fewer
  • documentCCEmail must contain at most 10 email addresses
  • redirect must be a valid URI or null
  • recipients must contain fewer than 200 items
  • senderFields and participantFields must contain fewer than 1000 items each

Invalid schedule or field payloads​

If you inline recipient schedules or field values:

  • each schedule item must include daysAfter, frequency, when, timeOfDay, subject, message, and skipWeekend
  • schedule when must be one of 1, 2, or 3
  • schedule subject and message must be 500 characters or fewer
  • each field input must include a valid element id
  1. Validate your payload locally with the Send Input JSON Schema.
  2. Run the mutation.
  3. If the mutation returns a validation error, correct the payload and retry.
  4. If the mutation returns a task ID, start polling task to monitor document creation.

When to Use Subscriptions Instead​

Polling task is a good fit for getting started, testing, and prototyping.

For production workflows, use subscriptions for real-time updates and treat polled task status as a fallback or prototyping tool.

For task-specific subscription guidance, see Track Send Tasks with Subscriptions.

Export This Article

Save a copy of this page as PDF or plain text.