CertCentral's Custom Reports API allows you to generate customizable and comprehensive data sets by leveraging the powerful GraphQL query language.
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.
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.
The GraphQL documentation covers features and functionality that might not be supported by CertCentral's Custom Reports API.
Use this base URL when constructing API requests:
https://www.digicert.com/services/v2/reportsQueries are used to generate data sets that are tailored to your specific needs. All queries are accessed using the /query endpoint.
Custom Reports API currently offers two queries: order_details and order_details_by_id.
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 orderslimit:5 – Truncates data to five resultssort:["valid_from","DESC"] – Sorts data using valid_from value in descending orderorder_details(status:"pending",limit:5,sort:["valid_from","DESC"])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:
idcommon_namepurchase_dns_namesstatusIn the response body, only the specified fields are returned.
You must include at least one field in the request. If no fields are included, a syntax error is returned.
{
order_details_by_id(id:123456) {
id
common_name
purchased_dns_names
status
}
}{
"data": {
"order_details_by_id": {
"id": "123456",
"common_name": "example.com",
"purchased_dns_names": "4",
"status": "issued"
}
}
}If no data exists for the field, a value of null is returned.
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.
To use Custom Reports API, you must include a DigiCert Developer API key in the request header. See Authentication for more information.
Requests to Custom Reports API use standard HTTP POST methods.
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.
You can construct and send a request body in one of two ways:
When converting GraphQL query syntax to a valid JSON string:
\").id,common_name,dns_names).query parameter in your JSON request body and set its value to the converted string.{
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
}
}{
"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}}"
}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.
{
new_customer_order: order_details_by_id(id:123456) {
id
common_name
purchased_dns_names
status
}
}{
"data": {
"new_customer_order": {
"id": "123456",
"common_name": "example.com",
"purchased_dns_names": "4",
"status": "issued"
}
}
}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.
{
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
}
}{
"data": {
"pending_orders": [
{
"id": "100010",
"status": "pending",
"common_name": "test.example.com",
"purchased_dns_names": "1",
"date_created": "2019-10-09 12:55:29"
},
{
"id": "100011",
"status": "pending",
"common_name": "monitor.example.com",
"purchased_dns_names": "1",
"date_created": "2019-10-08 16:54:55"
},
{
"id": "100012",
"status": "pending",
"common_name": "logs.example.com",
"purchased_dns_names": "1",
"date_created": "2019-10-08 14:03:22"
},
{
"id": "100013",
"status": "pending",
"common_name": "docs.example.com",
"purchased_dns_names": "1",
"date_created": "2019-10-08 12:50:42"
},
{
"id": "100014",
"status": "pending",
"common_name": "staging.example.com",
"purchased_dns_names": "1",
"date_created": "2019-10-08 10:08:03"
}
],
"issued_orders": [
{
"id": "100005",
"status": "issued",
"common_name": "example.com",
"purchased_dns_names": "0",
"date_created": "2019-10-04 17:56:36"
},
{
"id": "100006",
"status": "issued",
"common_name": "example.org",
"purchased_dns_names": "2",
"date_created": "2019-10-04 11:36:10"
},
{
"id": "100007",
"status": "issued",
"common_name": "example.net",
"purchased_dns_names": "1",
"date_created": "2019-10-04 04:05:41"
},
{
"id": "100008",
"status": "issued",
"common_name": "example.biz",
"purchased_dns_names": "4",
"date_created": "2019-10-02 06:32:54"
},
{
"id": "100009",
"status": "issued",
"common_name": "example.ca",
"purchased_dns_names": "0",
"date_created": "2019-09-30 08:04:18"
}
]
}
}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.
{
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
}
}{
"data": {
"cert_order_1": {
"id": "123456",
"common_name": "example.com",
"purchased_dns_names": "4",
"status": "issued",
"organization_id": "334455"
},
"cert_order_2": {
"status": "pending",
"common_name": "example.net",
"purchased_dns_names": "1",
"id": "123457",
"organization_id": "334455"
}
}
}