Skip to main content
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 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: 
query {
  deal(id: "123") {
    id
    status
  }
}
Response: 
{
  "data": {
    "deal": {
      "id": "123",
      "status": "ACTIVE"
    }
  }
}

​
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. 
query {
  deal(id: "123") {
    id
    status
    borrowers {
      id
      firstName
      lastName
      incomes {
        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. 
query {
  deal(id: "123") {
    id
    borrowers(first: 2) {
      id
      firstName
    }
  }
}

​
About mutations

Mutations are operations that modify data. They follow the same structure as queries, but they always start with mutation: 
mutation {
  createBorrower(
    input: { firstName: "John", lastName: "Doe", email: "[email protected]" }
  ) {
    id
    firstName
    lastName
  }
}

​
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. 
query GetDeal {
  deal(id: "123") {
    id
  }
}

mutation CreateBorrower {
  createBorrower(input: { firstName: "John", lastName: "Doe" }) {
    id
  }
}

​
Variables

Variables make queries more powerful and reusable. Instead of hardcoding values, you can pass them as separate variables. Query: 
query GetDeal($id: ID!) {
  deal(id: $id) {
    id
    status
  }
}
Variables: 
{
  "id": "123"
}
See the Variables and fragments guide for more details.

​
Making a call

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

​
Using curl

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 status } }"
  }'

​
Using fetch (JavaScript)

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
          status
        }
      }
    `,
    variables: {
      id: "123",
    },
  }),
});

const data = await response.json();

​
Working with responses

​
Checking for errors

Always check for errors in the response: 
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 for more details.

​
Partial data

GraphQL may return partial data even when some fields fail. Always check both data and errors: 
{
  "data": {
    "deal": {
      "id": "123",
      "status": "ACTIVE",
      "borrowers": null
    }
  },
  "errors": [
    {
      "message": "Failed to load borrowers",
      "path": ["deal", "borrowers"]
    }
  ]
}

​
Next steps