GraphQL Quickstart

This quickstart shows you how to use the GraphQL Explorer to:

• confirm your account is working with a simple query
• find your groupId and templateId
• send a test document with the minimum required fields
• poll the task report to confirm document creation has completed
• move the same flow into Node.js, Python, or C#

Before You Start

You need:

• API access enabled for your account. If you do not have it yet, contact us.
• A Legalesign account you can log into
• At least one group and one template in your account

Choose Authentication

The Explorer uses your logged-in Legalesign session. In your own code, GraphQL supports SRP authentication for full-schema access and API keys for a supported subset.

Mode	Coverage	Header	Best for
SRP	Full GraphQL schema	Authorization: Bearer <access-token>	Complete integrations
API Key	Supported subset only	Authorization: Bearer <api-key>	Server-side automation and common send/read flows

This quickstart uses SRP authentication in the language examples because it works across the full GraphQL schema. If you are using a Developer Portal API key, check the API-key GraphQL reference and the auth badges on reference pages.

Open the GraphQL Explorer

Go to the GraphQL Explorer.

info

If you're logged into Legalesign, authentication is automatic in the Explorer.

Copy and paste the queries below into the GraphQL Explorer to get started. Later, you'll use the same graphql in your own code.

Query Your User

Start with a harmless query to confirm the Explorer is working:

query MyUser {
  user {
    id
    firstName
    lastName
    email
  }
}

If this succeeds, your Explorer session is working and you are ready to look up the IDs needed for a send.

Query Your Groups

Next, list the groups your user belongs to:

query MyGroups {
  user {
    memberConnection(first: 10) {
      groupMembers {
        group {
          id
          name
        }
      }
    }
  }
}

Copy the id for the group you want to send from. This is your groupId.

Query Templates in That Group

Now query the templates in that group:

query GroupTemplates($groupId: ID!) {
  group(id: $groupId) {
    id
    name
    templateConnection(first: 10) {
      templates {
        id
        title
      }
    }
  }
}

Use these variables:

{
  "groupId": "<your-group-id>"
}

Copy the id for the template you want to send. This is your templateId.

Send Your First Document

Paste this mutation into the Explorer:

mutation SendDocument($input: DocumentSendSettingsInput!) {
  send(input: $input)
}

Add these variables and replace the placeholder values:

{
  "input": {
    "groupId": "<your-group-id>",
    "templateId": "<your-template-id>",
    "title": "Test Document",
    "recipients": [
      {
        "firstName": "Jane",
        "lastName": "Smith",
        "email": "jane@example.com",
        "order": 0
      }
    ]
  }
}

If the input is invalid, the mutation returns a validation error immediately.

If the mutation succeeds, it returns a task ID. Legalesign processes sends asynchronously, so the task starts the send job rather than waiting for delivery to complete.

Poll the Task Report

tip

Polling is fine for getting started. For production, you can switch to subscriptions to track send progress in real time instead.

After send, use the returned task ID to poll the task query:

query GetTask($id: ID!) {
  task(id: $id) {
    data
    report {
      status
      batchId
      documents
      errors
    }
  }
}

Use these variables:

{
  "id": "<task-id-from-send>"
}

The report field lets you confirm when document creation has completed after a valid send has started the async task.

Monitor report.status until it reaches a terminal state:

• COMPLETED means document creation has finished
• FAILED means document creation did not complete successfully

While the task is still running, you may see intermediate statuses such as PENDING or READY.

For getting started and prototyping, polling task is a simple way to check progress. For production, real-time updates are better handled with subscriptions.

See:

• task query
• TaskReport
• Troubleshoot Send Validation
• Subscription Examples
• Track Send Tasks with Subscriptions

tip

Use a real recipient email address you control while testing, so you can confirm the send completed as expected.

tip

You can also extract groupId and templateId from your dashboard and formes editor URLs - they are the only long alphanumeric in those URLs.

Move to Code

For programmatic access, first choose an authentication mode and get a token or API key. See Authenticate with the API.

Authenticate and Make a Request

Once you have your token or API key, send a GraphQL POST request with an Authorization header:

index.js

const GRAPHQL_ENDPOINT = 'https://graphql.uk.legalesign.com/graphql';
const TOKEN = '<token-or-api-key>';

async function graphql(token, query, variables = {}) {
    const response = await fetch(GRAPHQL_ENDPOINT, {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'Authorization': `Bearer ${token}`
        },
        body: JSON.stringify({ query, variables })
    });

    return response.json();
}

async function main() {
    const result = await graphql(TOKEN, `
        query {
            user {
                id
                firstName
                lastName
                email
            }
        }
    `);

    console.log(JSON.stringify(result, null, 2));
}

main().catch(console.error);

Next Steps

1. If you need language-specific setup, use Node.js Setup or C# Setup
2. If you want to create your own template first, follow Upload a File as a Template
3. Read Send a Document for the full Node.js code example
4. Browse the send mutation reference