OV/EV certificate lifecycle

To construct your request body and submit an order request, you need to collect some key pieces of information:

...
  "order_validity": {
    "years": 2
  },
...

...
  "order_validity": {
    "days": 900 
  },
...

...
  "order_validity": {
    "custom_expiration_date": "09 JUN 2025"
  },
...

...
  "certificate": {
    ...
      "cert_validity": {
      "years": 1
    }
  },
...

...
  "certificate": {
    ...
      "cert_validity": {
      "days": 100
    }
  },
...

...
  "certificate": {
    ...
      "cert_validity": {
      "custom_expiration_date": "01 MAY 2021"
    }
  },
...

Each OV/EV certificate order must include information about the organization that will receive the certificate. Before DigiCert can issue the certificate, industry standards require us to validate the organization you include in the request. For more information about organization validation, see TLS certificate organization validation process.

Use the organization object in the body of your request to submit the details of an organization with your order. You can use this object to create a new organization, or you can associate the certificate with an organization that already exists in your account.

"dcv_emails": [
  { 
    "dns_name": "example.com",
    "email_domain": "example.com",
    "email": "hostname@example.com"
  },
  { 
    "dns_name": "my.example.com",
    "email_domain": "example.com",
    "email": "admin@example.com"
  },
  { 
    "dns_name": "another.example.com",
    "email_domain": "example.com",
    "email": "admin@example.com"
  }
]

With ICA selection, you can choose which ICA certificate chain should issue your end-entity certificate.

To use ICA selection:

To select an ICA certificate chain, include the certificate.ca_cert_id parameter in your certificate request. The value of this parameter is the ID of the ICA certificate chain that should issue your end-entity certificate.

For example:

{
  "certificate": {
    "common_name": "example.test.com",
    "csr": {{csr}},
    "signature_hash": "sha256",
    "ca_cert_id": "4A7259E3E5D112A"
  },
  "order_validity": {
    "years": 1
  },
  "locale": "en",
  "skip_approval": true,
  "organization": {
    "id": {{organization_id}}
  },
  "payment_method": "profile"
}

After you collect the above information, you're ready to construct your request body and submit your order request. To do this, submit a POST request to the order endpoint for the type of certificate you want to buy.

The following table lists the endpoints for ordering different OV/EV SSL products:

A successful POST to an order endpoint returns a 201 Created HTTP response code. The response body includes information that you can use to check the status of the order and to download the certificate when it is issued, including:

The example below shows the entire request and response bodies for a sample request to the Order OV/EV SSL endpoint:

curl -X POST \
  'https://www.digicert.com/services/v2/order/certificate/{{ssl_certificate_id}}' \
  -H 'Content-Type: application/json' \
  -H 'X-DC-DEVKEY: {{api_key}}' \
  -d '{
    "certificate": {
        "common_name": "example.com",
        "dns_names": [
            "sub.example.com",
            "app.example.com"
        ],
        "csr": "<csr>",
        "server_platform": {
            "id": 45
        },
        "signature_hash": "sha256"
    },
    "order_validity": {
        "years": 1
    },
    "disable_renewal_notifications": true,
    "locale": "en",
    "skip_approval": true,
    "dcv_emails": [
      { 
        "dns_name": "example.com",
        "email_domain": "example.com",
        "email": "hostname@example.com"
      },
      { 
        "dns_name": "sub.example.com",
        "email_domain": "example.com",
        "email": "admin@example.com"
      },
      { 
        "dns_name": "app.example.com",
        "email_domain": "example.com",
        "email": "admin@example.com"
      }
    ]
    "payment_method": "balance",
    "organization": {
        "name": "Epigyne Unwieldiness llc",
        "assumed_name": "Epigyne Unwieldiness",
        "country": "us",
        "address": "932 Prospect Street",
        "address2": "Floor 08",
        "city": "Minneapolis",
        "state": "Minnesota",
        "zip": "40849",
        "telephone": "666-186-6450",
        "container": {
            "id": 93288
        },
        "organization_contact": {
            "first_name": "Gia",
            "last_name": "Booth",
            "job_title": "Clinical Laboratory Technician",
            "email": "gia.booth@inbox.com",
            "telephone": "666-186-6450",
            "telephone_extension": "736"
        }
    },
    "custom_fields": [
        {
            "metadata_id": 11,
            "value": "Invoice #00001"
        }
    ],
}'

{
  "id": 12345,
  "domains": [
    {
      "id": 12345,
      "name": "example.com",
      "dns_name": "example.com"
    },
    {
      "id": 12345,
      "name": "example.com",
      "dns_name": "sub.example.com"
    },
    {
      "id": 12345,
      "name": "example.com",
      "dns_name": "app.example.com"
    }
  ],
  "certificate_id": 123456
}

{
  "id": 12345,
  "dcv_random_value": {{token}},
  "domains": [
    {
      "id": 12345,
      "name": "example.com",
      "dns_name": "example.com",
      "dcv_token": {
        "token": {{token}},
        "status": "pending",
        "expiration_date": "2021-08-16T01:16:29+00:00"
      }
    },
    {
      "id": 12345,
      "name": "example.com",
      "dns_name": "sub.example.com"
      "dcv_token": {
        "token": {{token}},
        "status": "pending",
        "expiration_date": "2021-08-16T01:16:29+00:00"
    },
    {
      "id": 12345,
      "name": "example.com",
      "dns_name": "app.example.com"
      "dcv_token": {
        "token": {{token}},
        "status": "pending",
        "expiration_date": "2021-08-16T01:16:29+00:00"
    }
  ],
  "certificate_id": 123456
}

After placing an order, there may be times when you need to cancel it. To cancel an order, you need to change the status from pending to canceled. This is done with a PUT to the Update order status endpoint.

A successful PUT to this endpoint returns a 204 No Content HTTP response.

curl -X PUT \
  'https://www.digicert.com/services/v2/order/certificate/{{order_id}}/status' \
  -H 'Content-Type: application/json' \
  -H 'X-DC-DEVKEY: {{api_key}}' \
  -d '{
    "status": "CANCELED",
    "note": "Message about the cancellation."
}'

// empty

With the OV/EV order submitted, you now need to prove control over the domains on the order.

When you submit your certificate order, automatic domain control validation (DCV) polling begins immediately and runs for one week. For more information about automatic DCV polling, see Automatic domain control validation checks.

In addition to automatic DCV polling, you can perform a DCV check by calling the Check order DCV API endpoint. Alternatively, you can perform a DCV check from your CertCentral account by following these steps:

In addition to domain validation, all OV/EV orders also require organization validation. Once an order is submitted, DigiCert's validation team will begin working on the OV/EV organization validation process.

You can check the current validation status for an organization with a GET to the Organization Validation details endpoint.

A successful GET to this endpoint returns a 200 OK HTTP response.

curl -X GET \
  'https://www.digicert.com/services/v2/organization/{{organization_id}}/validation' \
  -H 'Content-Type: application/json' \
  -H 'X-DC-DEVKEY: {{api_key}}'

{
  "validations": [
    {
      "type": "ov",
      "name": "OV",
      "description": "Normal Organization Validation",
      "status": "pending"
    },
    {
      "type": "ev",
      "name": "EV",
      "description": "Extended Organization Validation (EV)",
      "status": "pending",
      "verified_users": [
        {
          "id": 12,
          "first_name": "John",
          "last_name": "Smith"
        }
      ]
    }
  ]
}

After submitting your order and completing the DCV for each domain, you'll want to know when the order status changes and the certificate is ready to download. The best way to do this is with a GET to the Status change list endpoint.

A GET to this endpoint returns three possible responses:

curl -X GET \
  'https://www.digicert.com/services/v2/order/certificate/status-changes?minutes=10' \
  -H 'Content-Type: application/json' \
  -H 'X-DC-DEVKEY: {{api_key}}'

{
  "orders": [
    {
      "order_id": 112233,
      "certificate_id": 123456,
      "status": "issued"
    }
  ]
}

{}

{
  "errors": [
    {
      "code": "time_frame_too_long",
      "message": "An error occurred while processing your request."
    }
  ]
}

Once the order status changes from pending to issued, your certificate is ready to be downloaded. Depending on your needs, there are four endpoints you can use to download your certificate:

Reissuing a certificate allows you to add, remove, or swap domain names, update the CSR, or change the signature hash of a certificate without submitting a new order. Additionally, if a certificate expires before the end of an order, you can reissue the certificate to receive a new certificate with a new expiration date.

A reissued certificate has a new certificate ID but the same order ID. After a reissue is approved, a new certificate is issued and needs to be reinstalled.

When reissuing a certificate, you need to provide this information:

Even if some of the above details are staying the same, you still need to include it in the reissue request.

The Reissue certificate endpoint accepts the following optional parameters:

The following example shows the full request and response bodies for a request to the reissue certificate endpoint:

curl -X POST \
  'https://www.digicert.com/services/v2/order/certificate/{{order_id}}/reissue' \
  -H 'Content-Type: application/json' \
  -H 'X-DC-DEVKEY: {{api_key}}' \
  -d '{
  "certificate": {
    "common_name": "example.com",
    "dns_names": [
        "sub.example.com"
    ],
    "csr": "<csr>",
    "server_platform": {
      "id": 2
    },
    "signature_hash": "sha256"
    "skip_approval": true
  }
}'

{
  "id": 112233,
  "dcv_random_value": {{token}},
  "certificate_id": 111112
}

{
  "id": 112233,
  "requests": [
    {
      "id": 332211
    }
  ]
}

After a reissue is complete, download the new certificate (see Download certificate).

You can get a complete reissue history for an order by using the List reissues endpoint.

Renewing an order allows you to link a new order to an expiring order such that you can track the history of your certificates using CertCentral and the Services API. When you renew an order, you receive a new certificate and a new order ID.

To renew, send a request to the endpoint for the certificate you want to buy. Follow the instructions to prepare the certificate request, and include a value for one of the following parameters:

For example, a request to renew the order with ID 123456 looks like this:

curl -X POST \
  'https://www.digicert.com/services/v2/order/certificate/{{ssl_certificate_id}}' \
  -H 'Content-Type: application/json' \
  -H 'X-DC-DEVKEY: {{api_key}}' \
  -d '{
    "certificate": {
        "common_name": "example.com",
        "dns_names": [
            "sub.example.com",
            "app.example.com"
        ],
        "csr": "<csr>",
        "server_platform": {
            "id": 45
        },
        "signature_hash": "sha256"
    },
    "order_validity": {
        "years": 2
    },
    "disable_renewal_notifications": true,
    "locale": "en",
    "renewal_of_order_id": 123456,
    "payment_method": "balance",
    "skip_approval": true,
    "organization": {
        "id": 123456
    },
    "custom_fields": [
        {
            "metadata_id": 11,
            "value": "Invoice #00001"
        }
    ]
}'

For renewal orders, the Order info response includes a true value for the is_renewal parameter. The value of the renewed_order_id parameter is the order ID for the previous order:

{
  "is_renewal": true,
  "renewed_order_id": 123456
}

After the status of the order renewal changes from pending to issued, you can download the new certificate (see Download certificate) and install it on your server. For more information about installing your certificate, see our SSL Certificate Installation Instructions & Tutorials page.

Once your order is issued, you can submit a revoke request if needed. You can revoke a certificate using one of two endpoints. Both endpoints use the same request body parameters.

After submitting the request, an administrator must approve it before DigiCert can revoke the certificate.

To skip the approval step and submit the request directly to DigiCert for revocation, include "skip_approval": true in the body of your request. To skip the approval step, the API key must have admin privileges. See Authentication.

curl --request PUT 'https://www.digicert.com/services/v2/certificate/{{certificate_identifier}}/revoke' \
--header 'Content-Type: application/json' \
--header 'X-DC-DEVKEY: {{api_key}}' \
--data-raw '{
  "skip_approval": true
}'

curl --request PUT 'https://www.digicert.com/services/v2/certificate/{{certificate_identifier}}/revoke' \
--header 'Content-Type: application/json' \
--header 'X-DC-DEVKEY: {{api_key}}' \
--data-raw '{
  "comments": "I no longer need this certificate."
}'

curl --request PUT 'https://www.digicert.com/services/v2/certificate/{{certificate_identifier}}/revoke' \
--header 'Content-Type: application/json' \
--header 'X-DC-DEVKEY: {{api_key}}' \
--data-raw '{
  "revocation_reason": "superseded",
  "skip_approval": true
}'

// empty

{
  "id": 1,
  "date": "2016-02-10T17:06:15+00:00",
  "type": "revoke",
  "status": "pending",
  "requester": {
    "id": 242140,
    "first_name": "Jack",
    "last_name": "White",
    "email": "j.white@fakeaddy.com"
  },
  "comments": "Revoked via API!"
}