Use GraphQL

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.

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

Get 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

1
query GetBusiness($id: ID!) {
2
  business(id: $id) {
3
    id
4
    name
5
    status
6
    createdAt
7
    updatedAt
8
    externalId
9
  }
10
}

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:

• list: 25 per page
• nested list: 10 per page

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

Forward pagination example:

1
query BusinessPeople($businessId: ID!, $first: Int!, $after: String) {
2
  business(id: $businessId) {
3
    id
4
    name
5
    people(first: $first, after: $after) {
6
      edges {
7
        cursor
8
        node {
9
          name
10
          submitted
11
          titles { title }
12
        }
13
      }
14
      pageInfo {
15
        hasNextPage
16
        endCursor
17
      }
18
    }
19
  }
20
}

This pattern is already supported across connections.

Mutations

To create a new business, use a mutation:

1
mutation {
2
  createBusiness(
3
    input: {
4
      name: "Middesk Inc"
5
      addresses: [
6
        { fullAddress: "85 2nd St. San Francisco CA 94105" }
7
      ]
8
    }
9
  ) {
10
    business {
11
      id
12
      name
13
      status
14
    }
15
    errors {
16
      message
17
    }
18
  }
19
}

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.

1
mutation {
2
  createOrder(
3
    input: {
4
      businessId: "888f2395-8a81-4a99-8628-13aa5c157963"
5
      package: "tin"
6
    }
7
  ) {
8
    order {
9
      id
10
      status
11
    }
12
    errors {
13
      message
14
    }
15
  }
16
}

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.

1
{
2
  "errors": [
3
    {
4
      "message": "Business not found",
5
      "locations": [
6
        {
7
          "line": 2,
8
          "column": 3
9
        }
10
      ],
11
      "path": [
12
        "business"
13
      ]
14
    }
15
  ],
16
  "data": {
17
    "business": null
18
  }
19
}

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.

1
{
2
  "data": {
3
    "createBusiness": {
4
      "business": null,
5
      "errors": [
6
        {
7
          "message": "Name can't be blank"
8
        }
9
      ]
10
    }
11
  }
12
}

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.

1
{
2
  "object": "business",
3
  "id": "32e7fb2c-60ca-4ddc-add2-694475b73f2b",
4
  "name": "Middesk Inc. ",
5
  "created_at": "2023-01-21T06:43:23.313Z",
6
  "updated_at": "2023-01-21T06:44:07.184Z",
7
  "status": "approved",
8
  "addresses": [
9
    {
10
      "object": "address",
11
      "address_line1": "2180 Bryant St Ste 210",
12
      "address_line2": null,
13
      "city": "San Francisco",
14
      "state": "CA",
15
      "postal_code": "94110-2141",
16
      "full_address": "2180 Bryant St Ste 210, San Francisco, CA 94110-2141",
17
      "latitude": 37.75938,
18
      "longitude": -122.40994,
19
      "created_at": "2019-01-30T23:49:01.100Z",
20
      "updated_at": "2019-01-30T23:49:01.100Z"
21
    }
22
  ]
23
  // .... Remaining business attributes
24
}

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.

1
query {
2
  business(id: "c3f1194a-d829-4320-b223-6a5ee24d9d19") {
3
    id
4
    status
5
    createdAt
6
    updatedAt
7
    addresses {
8
      nodes {
9
        fullAddress
10
        addressLine1
11
        addressLine2
12
        city
13
        state
14
      }
15
    }
16
    people {
17
      nodes {
18
        name
19
      }
20
    }
21
  }
22
}

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.

1
{
2
  "data": {
3
    "business": {
4
      "id": "c3f1194a-d829-4320-b223-6a5ee24d9d19",
5
      "name": "Middesk Inc.",
6
      "status": "in_review",
7
      "createdAt": "2025-11-26T19:33:30Z",
8
      "updatedAt": "2025-11-26T19:35:23Z",
9
      "addresses": {
10
        "nodes": [
11
          {
12
            "fullAddress": "85 2nd St. San Francisco CA, 94118",
13
            "addressLine1": "85 2nd St.",
14
            "city": "San Francisco",
15
            "state": "CA"
16
          }
17
        ]
18
      },
19
      "people": {
20
        "nodes": [
21
          {
22
            "name": "John Smith"
23
          }
24
        ]
25
      }
26
    }
27
  }
28
}

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:

1
query {
2
  business(id: "c3f1194a-d829-4320-b223-6a5ee24d9d19") {
3
    reviewTasks(keys: ["address_verification", "name"]) {
4
      nodes {
5
        key
6
        status
7
      }
8
    }
9
  }
10
}

The following response is returned with only the requested attributes.

1
{
2
  "data": {
3
    "business": {
4
      "reviewTasks": {
5
        "nodes": [
6
          {
7
            "key": "name",
8
            "status": "success"
9
          },
10
          {
11
            "key": "address_verification",
12
            "status": "success"
13
          }
14
        ]
15
      }
16
    }
17
  }
18
}

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