Skip to main content

Custom Reports GraphQL API

CertCentral's Custom Reports API allows you to generate customizable and comprehensive data sets by leveraging the powerful GraphQL query language.

Why use it?

Custom Reports API consolidates multiple REST endpoints into a single one, enabling you to better define the types and fields in your queries so they return only the information needed. Additionally, you can use it to create reusable query templates for generating and scheduling reports.

What is GraphQL?

GraphQL is an API query language that uses query sets to return only the data you need and nothing more. Learn more about GraphQL.

If you are new to GraphQL, we recommend taking a minute to read the GraphQL documentation to learn about the query language.

Note

The GraphQL documentation covers features and functionality that might not be supported by CertCentral's Custom Reports API.

Queries

Queries are used to generate data sets that are tailored to your specific needs. All queries are accessed using the following endpoint:

https://www.digicert.com/services/v2/reports/query

Custom Reports API currently offers two queries: order_details and order_details_by_id.

Arguments

Arguments are used with queries to further customize or manipulate returned data.

In this example, the order_details query includes three arguments:

  • status:"pending" – Returns only pending orders

  • limit:5 – Truncates data to five results

  • sort:["valid_from","DESC"] – Sorts data using valid_from value in descending order

order_details(status:"pending",limit:5,sort:["valid_from","DESC"])

Fields

Including or omitting fields in your query gives you the power to manipulate and customize the structure of the returned data.

In this example, the order_details_by_id query is used to return the details of a single certificate order. The request includes four fields:

  • id

  • common_name

  • purchase_dns_names

  • status

In the response body, only the specified fields are returned.

Important

You must include at least one field in the request. If no fields are included, a syntax error is returned.

Example 1. GraphQL
{
    order_details_by_id(id:123456) {
        id
        common_name
        purchased_dns_names
        status
    }
}

Notice

If no data exists for the field, a value of null is returned.

Requests

All API requests to Custom Reports API consist of three parts: method, endpoint, and body. The format of the body can either be application/graphql or application/json, depending on the syntax used to construct the body.

Note

To use Custom Reports API, you must include a DigiCert Developer API key in the request header. See Authentication for more information.

Method

Requests to Custom Reports API use standard HTTP POST methods.

Notice

Endpoints labeled with QUERY denote the endpoint's ability to accept GraphQL syntax using a GraphQL client; however, they still use the HTTP POST method.

Body

You can construct and send a request body in one of two ways:

  • Using GraphQL query syntax and sending the request via a GraphQL client.

  • Converting GraphQL query syntax to a valid JSON string and sending the request via a JSON payload.

When converting GraphQL query syntax to a valid JSON string:

  • Remove all new lines in the query (the string must be a single line).

  • Escape all double quotes (e.g., \").

  • Separate multiple fields with commas (e.g., id,common_name,dns_names).

  • Use the query parameter in your JSON request body and set its value to the converted string.

Example 3. GraphQL
{
    order_details(valid_till:"2020-10-26",status:"issued",limit:5,sort:["valid_from","DESC"]) {
        id
        common_name
        dns_names
        organization_id
        status
        valid_from
        valid_till
    }
}

Example 4. JSON
{
    "query": "{order_details(valid_till:\"2020-10-26\",status:\"issued\",limit:5,sort:[\"valid_from\",\"DESC\"]){id,common_name,dns_names,organization_id,status,valid_from,valid_till}}"
}

Tips and tricks

Custom query names

A query can be assigned a custom name that is reflected in the response body.

In this example, a custom name of new_customer_order is assigned to the order_details_by_id query. In the response body, the custom name is reflected as the name of the JSON object containing queried order information.

Example 5. GraphQL
{
    new_customer_order: order_details_by_id(id:123456) {
        id
        common_name
        purchased_dns_names
        status
    }
}

Send multiple queries

Send multiple queries with a single request using custom names for each query.

In this example, two separate order_details queries are sent in a single request using custom names for each. In the response body, the two queries are returned using the assigned custom names.

Example 7. GraphQL
{
    pending_orders: order_details(status:"pending",limit:5,sort:["date_created","DESC"]) {
        id
        status
        common_name
        purchased_dns_names
        date_created
    }
    issued_orders: order_details(status:"issued",limit:5,sort:["date_created","DESC"]) {
        id
        status
        common_name
        purchased_dns_names
        date_created
    }
}

Reorder response data

How you order the fields in a query determines how the information is ordered in the response body. This means you can arrange your query fields so the response body is in the desired order.

In this example, two order_details_by_id queries are sent requesting the same information. However, each query uses a different field order, which is reflected in the response body.

Example 9. GraphQL
{
    cert_order_1: order_details_by_id(id:123456) {
        id
        common_name
        purchased_dns_names
        status
        organization_id
    }
    cert_order_2: order_details_by_id(id:123457) {
        status
        common_name
        purchased_dns_names
        id
        organization_id
    }
}

In this section: