API Reference

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.

Base URL: https://api.middesk.com/graphql

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


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

A GraphQL API consists of a single endpoint. Unlike traditional REST APIs, which often use multiple endpoints for different resources and operations, GraphQL centralizes all interactions through this one 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

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]!