GraphQL

Overview

Middesk’s GraphQL API provides programmatic access to 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.

The GraphQL endpoint at Middesk is:

https://api.middesk.com/graphql

The public schema reference is available on Apollo Studio.

Authentication

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

Example request:

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

Getting Started

Using GraphQL

We recommend using a GraphQL client to introspect and explore the full schema. An API key can be used to interact with the API on Apollo Studio, which also can be used to view the lastest version of the schema. Our webhook behavior matches our REST API webhook design.

IDs and timestamps

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

Queries

Get a business by ID

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

Business with people

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

Business with addresses and a website

query GetBusinessDetails($id: ID!) {
  business(id: $id) {
    id
    name
    status
    addresses {
      nodes {
        # address fields
      }
      pageInfo { hasNextPage endCursor }
    }
    website { url }
  }
}

Business with TIN and formation

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

Connection-based pagination (relay-style)

Lists are returned 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:

businesses list: 25 per page
nested list: 10 per page

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

Forward pagination example:

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:

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

The mutation will create a new business and return its id, name, and status. Use the errors field to check for any issues creating the business. if a business fails to create, it will return as null with errors present.

A common use case after creating a business is to add additional orders. The createOrder mutation can be used for this purpose.

mutation {
  createOrder(
    input: {
      businessId: "888f2395-8a81-4a99-8628-13aa5c157963"
      package: "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. This errors appear in a top level errors array.

{
  "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 iwithinn an errors field describing the specific failures.

{
  "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 tohttps://api.middesk.com/v1/businesses/{id} retrieves the business for the given identifier (id).

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.

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

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

Via curl:

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 following response is returned with only the requested attributes.

{
  "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:

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

The following response is returned with only the requested attributes.

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

For more information or access, reach out to [email protected]!