--- title: "Custom Reports API" source_url: https://dev.digicert.com/certcentral-apis/custom-reports-api.html --- CertCentral's Custom Reports API allows you to generate customizable and comprehensive data sets by leveraging the powerful GraphQL query language. ## Available Report Types The available report types are: - Use the order_details query to get specific details for all certificate orders. - Use the order_details_by_id query to get specific details for a single certificate order. ## Why use it? Custom Reports GraphQL 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. The DigiCert CertCentral® Custom Reports GraphQL API integrates with your systems to: - Build custom datasets or reports by using specific queries and applying available filters to tailor the output. - Export flexible, JSON-based reports suitable for programmatic use. - Ideal for advanced reporting and integration with internal BI or monitoring tools. - 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. > **Info** > > 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: ```markup https://www.digicert.com/services/v2/reports/query ``` Custom Reports API currently offers two queries: [order_details](https://dev.digicert.com/md/certcentral-apis/custom-reports-api/order_details.md) and [order_details_by_id](https://dev.digicert.com/md/certcentral-apis/custom-reports-api/order_details_by_id.md). ### 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 ```graphql 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. ## GraphQL ```graphql { order_details_by_id(id:123456) { id common_name purchased_dns_names status } } ``` ## 200 OK ```json { "data": { "order_details_by_id": { "id": "123456", "common_name": "example.com", "purchased_dns_names": "4", "status": "issued" } } } ``` > **Info** > > 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. > **Info** > > To use Custom Reports API, you must include a DigiCert Developer API key in the request header. See [Authentication](https://dev.digicert.com/md/certcentral-apis/authentication.md) for more information. Also, verify that your account has the necessary permissions to execute specific API request. For more information, see [Check permission](https://dev.digicert.com/md/certcentral-apis/services-api/authorization/check-permission.md). ### Method Requests to Custom Reports API use standard HTTP **POST** methods. > **Info** > > 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. **GraphQL** ```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 } } ``` **JSON** ```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. ## GraphQL ```graphql { new_customer_order: order_details_by_id(id:123456) { id common_name purchased_dns_names status } } ``` ## 200 OK ```json { "data": { "new_customer_order": { "id": "123456", "common_name": "example.com", "purchased_dns_names": "4", "status": "issued" } } } ``` ### 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. ## GraphQL ```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 } } ``` ## 200 OK ```json { "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" } ] } } ``` ### 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. To view the errors returned by the DigiCert CertCentral® API and their descriptions, see [Errors](https://dev.digicert.com/md/certcentral-apis/services-api/errors.md). 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. ## GraphQL ```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 } } ``` ## 200 OK ```json { "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" } } } ``` ## In this section - [order_details](https://dev.digicert.com/md/certcentral-apis/custom-reports-api/order_details.md) - [order_details_by_id](https://dev.digicert.com/md/certcentral-apis/custom-reports-api/order_details_by_id.md)