> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pylon.mortgage/llms.txt
> Use this file to discover all available pages before exploring further.

# Forming calls with GraphQL

> Learn how to structure GraphQL queries and mutations for the Pylon API

This guide shows you how to form calls to the Pylon GraphQL API. You'll learn how to authenticate, structure queries and mutations, and work with the response.

## Authenticating requests

All requests to the Pylon GraphQL API require authentication. Include your access token in the `Authorization` header:

```
Authorization: Bearer YOUR_ACCESS_TOKEN
```

See the [GraphQL authentication](/playground/authentication) guide for details on obtaining access tokens.

## The GraphQL endpoint

The Pylon GraphQL API uses a single endpoint for all operations:

* **Production**: `https://pylon.mortgage/graphql`
* **Sandbox**: `https://sandbox.pylon.mortgage/graphql`

## About queries

Queries allow you to ask for specific fields on objects. Here's a simple query and its response:

**Query:**

```graphql theme={null}
query {
  deal(id: "123") {
    id
    friendlyId
  }
}
```

**Response:**

```json theme={null}
{
  "data": {
    "deal": {
      "id": "123",
      "friendlyId": "PYL-1042"
    }
  }
}
```

## Query fields

GraphQL queries are hierarchical and composed of fields. A field can be a scalar (like a string or number) or an object that contains its own fields.

```graphql theme={null}
query {
  deal(id: "123") {
    id
    friendlyId
    borrowers {
      edges {
        node {
          id
          personalInformation {
            firstName
            lastName
          }
          incomes {
            edges {
              node {
                statedMonthlyAmount
                payPeriodFrequency
              }
            }
          }
        }
      }
    }
  }
}
```

## Arguments

You can pass arguments to fields. Arguments can be scalars or enums, and are used to filter or specify the data you want.

```graphql theme={null}
query {
  deal(id: "123") {
    id
    borrowers(first: 2) {
      edges {
        node {
          id
          personalInformation {
            firstName
          }
        }
      }
    }
  }
}
```

## About mutations

Mutations are operations that modify data. They follow the same structure as queries, but they always start with `mutation`:

```graphql theme={null}
mutation {
  borrower {
    create(
      input: {
        dealId: "123"
        personalInformation: {
          firstName: "John"
          lastName: "Doe"
          email: "john.doe@example.com"
        }
      }
    ) {
      id
    }
  }
}
```

## Operation names

Operation names are meaningful and explicit names for your operations. They are only required in multi-operation documents, but using them is helpful for debugging and server-side logging.

```graphql theme={null}
query GetDeal {
  deal(id: "123") {
    id
  }
}

mutation CreateBorrower {
  borrower {
    create(
      input: {
        dealId: "123"
        personalInformation: {
          firstName: "John"
          lastName: "Doe"
          email: "john.doe@example.com"
        }
      }
    ) {
      id
    }
  }
}
```

## Variables

Variables make queries more powerful and reusable. Instead of hardcoding values, you can pass them as separate variables.

**Query:**

```graphql theme={null}
query GetDeal($id: ID!) {
  deal(id: $id) {
    id
    friendlyId
  }
}
```

**Variables:**

```json theme={null}
{
  "id": "123"
}
```

See the [Variables and fragments guide](/playground/variables-fragments) for more details.

## Making a call

You can make GraphQL calls using `curl`, any HTTP client, or a GraphQL client library.

### Using curl

```bash theme={null}
curl -X POST https://pylon.mortgage/graphql \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query { deal(id: \"123\") { id friendlyId } }"
  }'
```

### Using fetch (JavaScript)

```javascript theme={null}
const response = await fetch("https://pylon.mortgage/graphql", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${accessToken}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: `
      query GetDeal($id: ID!) {
        deal(id: $id) {
          id
          friendlyId
        }
      }
    `,
    variables: {
      id: "123",
    },
  }),
});

const data = await response.json();
```

## Working with responses

### Checking for errors

Always check for errors in the response:

```javascript theme={null}
const result = await response.json();

if (result.errors) {
  // Handle errors
  console.error("GraphQL errors:", result.errors);
} else {
  // Use the data
  console.log("Data:", result.data);
}
```

See the [Error handling guide](/playground/error-handling) for more details.

### Partial data

GraphQL may return partial data even when some fields fail. Always check both `data` and `errors`:

```json theme={null}
{
  "data": {
    "deal": {
      "id": "123",
      "friendlyId": "PYL-1042",
      "borrowers": null
    }
  },
  "errors": [
    {
      "message": "Failed to load borrowers",
      "path": ["deal", "borrowers"]
    }
  ]
}
```

## Next steps

* Learn about [variables and fragments](/playground/variables-fragments)
* Understand [pagination](/playground/pagination)
* Explore [using GraphQL clients](/playground/using-clients)