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
• 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

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 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.

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, use the same OAuth username/password flow (USER_PASSWORD_AUTH) with your Legalesign username and password. Contact Legalesign support to obtain your Client ID.

Authenticate and Make a Request

This is the same flow in every language:

1. Request an access token from Cognito with USER_PASSWORD_AUTH
2. Send a GraphQL POST request with Authorization: Bearer <access-token>

Node.js

index.js

const LEGALESIGN_AUTH_ENDPOINT = 'https://cognito-idp.eu-west-2.amazonaws.com';
const GRAPHQL_ENDPOINT = 'https://graphql.uk.legalesign.com/graphql';
const CLIENT_ID = '<your-client-id>';
const USERNAME = '<your-username>';
const PASSWORD = '<your-password>';

async function getToken() {
    const response = await fetch(LEGALESIGN_AUTH_ENDPOINT, {
        method: 'POST',
        headers: {
            'Content-Type': 'application/x-amz-json-1.1',
            'X-Amz-Target': 'AWSCognitoIdentityProviderService.InitiateAuth'
        },
        body: JSON.stringify({
            AuthFlow: 'USER_PASSWORD_AUTH',
            ClientId: CLIENT_ID,
            AuthParameters: {
                USERNAME,
                PASSWORD
            }
        })
    });

    const data = await response.json();
    if (data.__type) {
        throw new Error(`Authentication failed: ${data.message}`);
    }

    return data.AuthenticationResult.AccessToken;
}

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 token = await getToken();

    const result = await graphql(token, `
        query {
            user {
                id
                firstName
                lastName
                email
            }
        }
    `);

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

main().catch(console.error);

Python

auth_example.py

import json
import requests

LEGALESIGN_AUTH_ENDPOINT = 'https://cognito-idp.eu-west-2.amazonaws.com'
GRAPHQL_ENDPOINT = 'https://graphql.uk.legalesign.com/graphql'
CLIENT_ID = '<your-client-id>'
USERNAME = '<your-username>'
PASSWORD = '<your-password>'

def get_access_token():
    response = requests.post(
        LEGALESIGN_AUTH_ENDPOINT,
        json={
            'AuthFlow': 'USER_PASSWORD_AUTH',
            'ClientId': CLIENT_ID,
            'AuthParameters': {
                'USERNAME': USERNAME,
                'PASSWORD': PASSWORD
            }
        },
        headers={
            'Content-Type': 'application/x-amz-json-1.1',
            'X-Amz-Target': 'AWSCognitoIdentityProviderService.InitiateAuth'
        }
    )
    response.raise_for_status()
    return response.json()['AuthenticationResult']['AccessToken']

def graphql(token, query, variables=None):
    response = requests.post(
        GRAPHQL_ENDPOINT,
        headers={
            'Content-Type': 'application/json',
            'Authorization': f'Bearer {token}'
        },
        json={'query': query, 'variables': variables or {}}
    )
    response.raise_for_status()
    return response.json()

def main():
    token = get_access_token()

    result = graphql(token, """
        query {
            user {
                id
                firstName
                lastName
                email
            }
        }
    """)

    print(json.dumps(result, indent=2))

if __name__ == '__main__':
    main()

C#

Program.cs

using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;

class Program
{
    static async Task<string> GetTokenAsync(HttpClient httpClient)
    {
        var requestBody = new
        {
            AuthFlow = "USER_PASSWORD_AUTH",
            ClientId = "<your-client-id>",
            AuthParameters = new
            {
                USERNAME = "<your-username>",
                PASSWORD = "<your-password>"
            }
        };

        var request = new HttpRequestMessage
        {
            Method = HttpMethod.Post,
            RequestUri = new Uri("https://cognito-idp.eu-west-2.amazonaws.com"),
            Content = new StringContent(
                JsonSerializer.Serialize(requestBody),
                Encoding.UTF8,
                "application/x-amz-json-1.1"
            )
        };
        request.Headers.Add("X-Amz-Target", "AWSCognitoIdentityProviderService.InitiateAuth");

        var response = await httpClient.SendAsync(request);
        response.EnsureSuccessStatusCode();

        var json = await response.Content.ReadAsStringAsync();
        var doc = JsonSerializer.Deserialize<JsonElement>(json);
        return doc.GetProperty("AuthenticationResult").GetProperty("AccessToken").GetString()!;
    }

    static async Task Main()
    {
        using var httpClient = new HttpClient();
        var token = await GetTokenAsync(httpClient);

        httpClient.DefaultRequestHeaders.Authorization =
            new AuthenticationHeaderValue("Bearer", token);

        var queryObject = new
        {
            query = @"query {
                user {
                    id
                    firstName
                    lastName
                    email
                }
            }",
            variables = new { }
        };

        var request = new HttpRequestMessage
        {
            Method = HttpMethod.Post,
            RequestUri = new Uri("https://graphql.uk.legalesign.com/graphql"),
            Content = new StringContent(
                JsonSerializer.Serialize(queryObject),
                Encoding.UTF8,
                "application/json"
            )
        };

        var response = await httpClient.SendAsync(request);
        response.EnsureSuccessStatusCode();

        var responseString = await response.Content.ReadAsStringAsync();
        Console.WriteLine(responseString);
    }
}

For the raw request format and more detail on the token request, see the authentication guide.

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