> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.middesk.com/build/graphql/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.middesk.com/_mcp/server.

# Use GraphQL

> Query Middesk business data using the GraphQL API for flexible, efficient data retrieval.

Middesk provides an optional GraphQL API for accessing business verification and identity data. It enables you to query the business identity, associated people, addresses, and other related compliance and risk insights through a flexible GraphQL interface. Unlike traditional REST APIs, which often use multiple endpoints for different resources and operations, GraphQL centralizes all interactions through a single endpoint. Interaction with the API is via GraphQL queries and mutations. The queries provide an interface to return only the fields requested.

> **Note**
>
> Use of the GraphQL API is optional and contains a subset of all available functionality. It can offer some benefits, but use the traditional REST API if it better suits your use case.
>
> The GraphQL endpoint at Middesk is: `https://api.middesk.com/graphql`
>
> Apollo Studio hosts the public [schema reference](https://studio.apollographql.com/public/Middesk/variant/current/schema/reference).

## Authentication

Send your API credentials in the `Authorization` header as a Bearer Token.

Example request:

```bash
curl -X POST https://api.middesk.com/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: <YOUR_API_CREDENTIALS>" \
  --data '{"query":"query { business(id: \"business_123456\") { id name status } }"}'
```

## Get started

### Using GraphQL

Use a GraphQL client to introspect and explore the full schema. Use an API key to interact with the API on [Apollo Studio](https://studio.apollographql.com/public/Middesk/variant/current/home), which also shows the latest version of the schema. Middesk's webhook behavior matches the [REST API webhook design](https://docs.middesk.com/reference/webhooks).

### IDs and timestamps

* IDs use the GraphQL `ID` scalar
* Timestamps are ISO8601.
* Fields marked with `!` are non-nullable in the schema.

## Queries

#### Retrieve by ID

```graphql
query GetBusiness($id: ID!) {
  business(id: $id) {
    id
    name
    status
    createdAt
    updatedAt
    externalId
  }
}
```

#### With people

```graphql
query GetBusinessWithPeople($id: ID!) {
  business(id: $id) {
    id
    name
    status
    people {
      nodes {
        name
        submitted
        titles { title }
      }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
  }
}
```

#### With addresses and website

```graphql
query GetBusinessDetails($id: ID!) {
  business(id: $id) {
    id
    name
    status
    addresses {
      nodes {
        fullAddress
      }
      pageInfo { hasNextPage endCursor }
    }
    website { url }
  }
}
```

#### With TIN and formation

```graphql
query GetBusinessTaxInfo($id: ID!) {
  business(id: $id) {
    id
    name
    tin {
      tin
    }
    formation {
      entityType
      state
      date
    }
  }
}
```

## Connection-based pagination (relay-style)

The API returns lists as "connections" (for example, people, names, addresses, businesses). Connections support cursor-based pagination via:

* `first` / `after` for forward pagination
* `last` / `before` for backward pagination

Each connection includes:

* `edges { cursor node { ... } }`
* `nodes { ... }` (convenience)
* `pageInfo { hasNextPage hasPreviousPage startCursor endCursor }`

### Page-size limits

To keep responses predictable, paginate within these limits:

* list: 25 per page
* nested list: 10 per page

If you request more than the limit, results may be clamped.

Forward pagination example:

```graphql
query BusinessPeople($businessId: ID!, $first: Int!, $after: String) {
  business(id: $businessId) {
    id
    name
    people(first: $first, after: $after) {
      edges {
        cursor
        node {
          name
          submitted
          titles { title }
        }
      }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
  }
}
```

This pattern is already supported across connections.

## Mutations

To create a new business, use a mutation:

```graphql
mutation {
  createBusiness(
    input: {
      name: "Middesk Inc"
      addresses: [
        { fullAddress: "85 2nd St. San Francisco CA 94105" }
      ]
    }
  ) {
    business {
      id
      name
      status
    }
    errors {
      message
    }
  }
}
```

The mutation creates a new business and returns its `id`, `name`, and `status`. Use the `errors` field to check for any issues creating the business. If a business fails to create, the mutation returns `null` with `errors` present.

A common use case after creating a business is to add additional orders. Use the `createOrder` mutation for this purpose.

```graphql
mutation {
  createOrder(
    input: {
      businessId: "888f2395-8a81-4a99-8628-13aa5c157963"
      product: "tin"
    }
  ) {
    order {
      id
      status
    }
    errors {
      message
    }
  }
}
```

## Errors

Middesk's GraphQL API follows the standard GraphQL error format, returning errors within an errors array in the response. Each error object includes a message describing what went wrong.

Always check for the errors array before assuming success—GraphQL queries can partially succeed with a `200` HTTP status, returning some data while including errors for failed fields. Monitor HTTP status codes for server errors (5xx). Use strongly-typed GraphQL clients when possible to catch validation errors at development time, and always validate required fields to avoid runtime null value errors.

### System-level errors

System-level errors indicate that the GraphQL request could not be executed normally. These errors appear in a top level errors array.

```json
{
  "errors": [
    {
      "message": "Business not found",
      "locations": [
        {
          "line": 2,
          "column": 3
        }
      ],
      "path": [
        "business"
      ]
    }
  ],
  "data": {
    "business": null
  }
}
```

### Mutation-level errors

For business logic or validation failures within a mutation, the API does not use the top level errors array. Instead, each mutation returns a result payload that may contain errors within an `errors` field describing the specific failures.

```json
{
  "data": {
    "createBusiness": {
      "business": null,
      "errors": [
        {
          "message": "Name can't be blank"
        }
      ]
    }
  }
}
```

## REST API vs. GraphQL API

The following example demonstrates the differences between using Middesk's REST API and its GraphQL API.

### REST API

**Retrieving a business**

Sending a GET request to`https://api.middesk.com/v1/businesses/{id}` retrieves the business for the given identifier (`id`).

```bash
curl https://api.middesk.com/v1/businesses/51c4b91e-f324-467b-86b5-9e0155bcc251 \
  -u mk_live_50e41b726c05c15cbf8bc13f: \
  -H "Accept: application/json"
```

The returned response consists of the entire business payload with all attributes.

```json
{
  "object": "business",
  "id": "32e7fb2c-60ca-4ddc-add2-694475b73f2b",
  "name": "Middesk Inc. ",
  "created_at": "2023-01-21T06:43:23.313Z",
  "updated_at": "2023-01-21T06:44:07.184Z",
  "status": "approved",
  "addresses": [
    {
      "object": "address",
      "address_line1": "2180 Bryant St Ste 210",
      "address_line2": null,
      "city": "San Francisco",
      "state": "CA",
      "postal_code": "94110-2141",
      "full_address": "2180 Bryant St Ste 210, San Francisco, CA 94110-2141",
      "latitude": 37.75938,
      "longitude": -122.40994,
      "created_at": "2019-01-30T23:49:01.100Z",
      "updated_at": "2019-01-30T23:49:01.100Z"
    }
  ]
  // .... Remaining business attributes
}
```

While simple to use, the payload contains more data than may be needed, depending on the use case. Interacting with the API necessitates navigating a large payload to find relevant information.

### GraphQL API

**Retrieving a business**

Send a POST request to `https://api.middesk.com/graphql` with the following GraphQL query to retrieve a business.

```graphql
query {
  business(id: "c3f1194a-d829-4320-b223-6a5ee24d9d19") {
    id
    status
    createdAt
    updatedAt
    addresses {
      nodes {
        fullAddress
        addressLine1
        addressLine2
        city
        state
      }
    }
    people {
      nodes {
        name
      }
    }
  }
}
```

Via curl:

```bash
curl https://api.middesk.com/graphql \
  -u "mk_live_2c893ffd700264c02a65baa3:" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "query": "
      query {
        business(id: \"c3f1194a-d829-4320-b223-6a5ee24d9d19\") {
          id
          name
          status
          createdAt
          updatedAt
          addresses {
            nodes {
              fullAddress
              addressLine1
              city
              state
            }
          }
          people {
            nodes {
              name
            }
          }
        }
      }
    "
  }'
```

The response includes only the requested attributes.

```json
{
  "data": {
    "business": {
      "id": "c3f1194a-d829-4320-b223-6a5ee24d9d19",
      "name": "Middesk Inc.",
      "status": "in_review",
      "createdAt": "2025-11-26T19:33:30Z",
      "updatedAt": "2025-11-26T19:35:23Z",
      "addresses": {
        "nodes": [
          {
            "fullAddress": "85 2nd St. San Francisco CA, 94118",
            "addressLine1": "85 2nd St.",
            "city": "San Francisco",
            "state": "CA"
          }
        ]
      },
      "people": {
        "nodes": [
          {
            "name": "John Smith"
          }
        ]
      }
    }
  }
}
```

\


**Another example**

The GraphQL API supports fetching only the data needed. For example, a user can check only the name and address verification outcomes of a business by using the following GraphQL query:

```graphql
query {
  business(id: "c3f1194a-d829-4320-b223-6a5ee24d9d19") {
    reviewTasks(keys: ["address_verification", "name"]) {
      nodes {
        key
        status
      }
    }
  }
}
```

The response includes only the requested attributes.

```json
{
  "data": {
    "business": {
      "reviewTasks": {
        "nodes": [
          {
            "key": "name",
            "status": "success"
          },
          {
            "key": "address_verification",
            "status": "success"
          }
        ]
      }
    }
  }
}
```

The GraphQL API allows users to fine-tune their usage of Middesk's product.

\


> **Get a demo**
>
> Contact your account manager or [contact sales](https://www.middesk.com/contact-sales) to inquire about access.

> Query Middesk business data using the GraphQL API for flexible, efficient data retrieval.