Neidio i’r prif gynnwys

send

SRPAPI Key

Send a document for signing in a single API call. Invalid input is rejected immediately. Valid input returns a task ID that can be polled via the task query.

Input​

DocumentSendSettingsInput — passed as AWSJSON. See the complete JSON structure for all fields.

Return Type​

ID — the task ID for a valid send request. Poll with the task query and monitor task.report.status until it reaches COMPLETED or FAILED.

Get template roles​

If your workflow needs template role mapping, query the template to get the roleId values for recipients:

query GetTemplateRoles($id: ID!) {
  template(id: $id) {
    title
    roles {
      id
      name
      roleType
    }
  }
}

Each role id in the response can be used as roleId in the recipients array when you need to map recipients to template roles.

Minimal example (required fields only)​

mutation SendDocument {
  send(input: {
    groupId: "Z3JwMTIzNDU2"
    templateId: "dHBsMTIzNDU2"
    title: "Employment Contract - Jane Smith"
    recipients: [
      {
        firstName: "Jane"
        lastName: "Smith"
        email: "jane@example.com"
        order: 0
      }
    ]
  })
}

All other fields are optional. When omitted, sequentialSigning, allowCopying, allowPrinting, pdfPassword, retainPdfPassword, and documentCCEmail use the group defaults. suppressEmails defaults to false, and tag defaults to "".

Full example (all fields)​

mutation SendDocument {
  send(input: {
    groupId: "Z3JwMTIzNDU2"
    templateId: "dHBsMTIzNDU2"
    title: "Employment Contract - Jane Smith"
    sequentialSigning: true
    allowCopying: false
    allowPrinting: false
    tag: ""
    pdfPassword: ""
    retainPdfPassword: false
    suppressEmails: false
    documentCCEmail: []
    redirect: ""
    recipients: [
      {
        roleId: "cm9sMTIzNDU2"
        firstName: "Jane"
        lastName: "Smith"
        email: "jane@example.com"
        order: 0
        phoneNumber: ""
        experience: "ZXhwMTIzNDU2"
        scheduleId: "c2NoMTIzNDU2"
        message: "Dear {{signer_firstname}},\n\nPlease sign {{doc_name}}.\n\nContact {{sender_fullname}} with questions."
        attachments: ["YXR0MTIzNDU2"]
        expiryDate: null
        timeZone: "Europe/London"
        ccEmail: "manager@example.com"
        ccFirstName: "Bob"
        ccLastName: "Jones"
        ccMessage: "For your records."
        ccIncludeLink: true
      }
    ]
    senderFields: [
      { id: "ZWxlMTIzNDU2", value: "Acme Corp" }
    ]
    participantFields: [
      { id: "ZWxlNzg5MDEy", value: "" }
    ]
  })
}

Key notes:

  • roleId is optional. When provided, it should be the base64-encoded template role ID used to link the recipient to template fields.
  • experience is optional. When provided, it must be base64-encoded and decode to exp plus a non-empty suffix; the suffix may be a UUID or a slug-like value.
  • message supports placeholders: {{signer_firstname}}, {{signer_lastname}}, {{sender_fullname}}, {{doc_name}}.
  • expiryDate is ISO 8601 or null for no expiry.
  • To skip a recipient, omit them from the array entirely.

Where to get the IDs​

FieldQuery
groupIdgroup
templateIdtemplate — via Group.templateConnection
roleId (optional)template — roles { id }
experienceexperience — via Group.experienceConnection
scheduleIdschedule — via Group.scheduleConnection
attachmentsattachment — via Group.attachmentConnection
senderFields / participantFields idtemplate — elementConnection { templateElements { id } }

Sending patterns​

There are three ways to send documents:

Single send​

One mutation, one document:

send(input: { ... }) → task ID

Batch send​

Multiple documents grouped together with shared notification settings. Documents are sent when the batch is started.

1. sendBatch(input: { groupId, batchName, ... })        → batch ID (UUID)
2. sendBatchDocument(input: { batchId, document: { ... } })  × N
3. startBatch(input: { batchId })                        → sends all

See sendBatch, sendBatchDocument, startBatch.

Bulk send​

Same template sent to different recipients. Each call to addBulkDocument queues one recipient set.

1. startBulk(input: { groupId, name })                   → bulk ID (UUID)
2. addBulkDocument(input: { bulkId, document: { ... } })  × N
3. sendBulk(input: { groupId, bulkId, name, ... })       → sends all

See startBulk, addBulkDocument, sendBulk.

Batch and bulk document fields use the same DocumentSendSettingsInput structure as single send. The batchId and bulkId returned are plain UUIDs, not base64-encoded.

The same validation rules also apply when this input is nested under document in sendBatchDocument and addBulkDocument, including ID-shape checks, string length limits, and collection size limits.

Export This Article

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