Home
/
API reference
/
Certificate process automation

Tasks for managing certificate orders

API processes · Updated 2023-09-27

The API allows you to view and manage running and completed orders.

Basics of the JSON and XML API

All important information for the use of the JSON and XML API you can find in the General API Basics and the XML API Basics and JSON API Basics. The specific SSL objects are documented here, the SSL tasks here.

Listing running and completed orders

With a list inquire request you can use the JSON and XML API to query all running and completed orders.

POST /job/_search 
POST /job/history/_search
{
	"view": {
		"limit": 10,
        "offset": 0
    }
}

{
  "stid": "20180926-stid",
  "status": {
    "code": "S300115",
    "text": "Request data has been inquired successfully.",
    "type": "SUCCESS"
  },
  "object": {
    "type": "ObjectJob",
    "summary": 1
  },
  "data": [
    {
      "job": {
        "created": "2019-10-23T16:12:33.000+0200",
        "updated": "2019-10-23T17:26:01.000+0200",
        "owner": {
          "context": 9,
          "user": "user"
        },
        "updater": {
          "context": 9,
          "user": "user"
        },
        "status": "DEFFERED",
        "subStatus": "WF_EMAIL_AUTH",
        "execution": "2019-10-23T17:25:58.000+0200",
        "subType": "RAPID_SSL",
        "action": "create",
        "id": 12345
      },
      "object": {
        "type": "Certificate",
        "value": "domain.de"
      }
    }
  ]
}

<task>
	<code>400115</code><!-- History 400135--> 
	<view>
		<limit>10</limit>
		<offset>0</offset>
	</view>
</task>

<response>
	<result>
		<data>
			<summary>1</summary>
			<certificate_job>
				<job>
					<id>12345</id>
					<owner>
						<user>user</user>
						<context>9</context>
					</owner>
					<updater>
						<user>user</user>
						<context>9</context>
					</updater>
					<object>domain.de</object>
					<status>DEFFERED</status>
					<sub_status>WF_EMAIL_AUTH</sub_status>
					<created>2019-10-23 16:12:33</created>
					<updated>2019-10-23 17:26:01</updated>
					<type>ssl</type>
					<sub_type>RAPID_SSL</sub_type>
					<action>create</action>
					<execution>2019-10-23 17:25:58</execution>
				</job>
			</certificate_job>
		</data>
		<status>
			<code>S400115</code>
			<text>Certificate orders were inquired successfully.</text>
			<type>success</type>
		</status>
	</result>
	<stid>20200228-stid</stid>
</response>

Displaying data of a running or completed job

The API offers the possibility to display details for a running or completed order. This includes, for example:

Data for the Domain Control Validation (DCV)
Status of the order on the CA side
The certificate data such as the CSR used

GET /job/{id}
GET /job/history/{id

{
  "stid": "20200228-stid",
  "status": {
    "code": "S300114",
    "text": "The workflow order was inquired succesfully.",
    "type": "SUCCESS"
  },
  "object": {
    "type": "ObjectJob",
    "value": "12345"
  },
  "data": [
    {
      "job": {
        "created": "2019-10-23T16:12:33.000+0200",
        "updated": "2019-10-23T17:26:01.000+0200",
        "owner": {
          "context": 9,
          "user": "user"
        },
        "updater": {
          "context": 9,
          "user": "user"
        },
        "status": "DEFFERED",
        "subStatus": "WF_EMAIL_AUTH",
        "execution": "2019-10-23T17:25:58.000+0200",
        "subType": "RAPID_SSL",
        "action": "create",
        "id": 12345
      },
      "object": {
        "type": "Certificate",
        "value": "domain.de",
        "data": {
          "created": "2019-10-23T00:00:00.000+0200",
          "partnerOrderId": "IX-CC-12345",
          "orderId": "9202720",
          "adminContact": {
            "fname": "Jon",
            "lname": "Doe",
            "phone": "+49-0-0",
            "fax": "+49-0-0",
            "email": "jon.doe@domain.de",
            "title": "Herr",
            "organization": "Muster GmbH",
            "address": [
              "Musterstrasse 6"
            ],
            "pcode": "12345",
            "city": "Musterstadt",
            "country": "DE",
            "state": "Bayern",
            "id": 1
          },
          "technicalContact": {
            "fname": "Jon",
            "lname": "Doe",
            "phone": "+49-0-0",
            "fax": "+49-0-0",
            "email": "jon.doe@domain.de",
            "title": "Herr",
            "organization": "Muster GmbH",
            "address": [
              "Musterstrasse 6"
            ],
            "pcode": "12345",
            "city": "Musterstadt",
            "country": "DE",
            "state": "Bayern",
            "id": 1
          },
          "name": "domain.de",
          "lifetime": {
            "unit": "MONTH",
            "period": 12
          },
          "software": "APACHE2",
          "csr": "-----BEGIN CERTIFICATE REQUEST-----\n ... \n-----END CERTIFICATE REQUEST-----",
          "product": "RAPID_SSL",
          "signatureHashAlgorithm": "SHA2_FULL_CHAIN",
          "expire": "2020-10-23T00:00:00.000+0200",
          "certificationAuthority": [],
          "authentication": {
            "method": "EMAIL",
            "approverEmails": [
              "admin@domain.de"
            ]
          },
          "certificateTransparencyPrivacy": "PUBLIC"
        }
      }
    }
  ]
}

<request>
	<auth>
		<user>USER</user>
		<context>CONTEXT</context>
		<password>PASSWORD</password>
	</auth>
	<task>
		<code>400114</code><!-- History 400134-->
		<certificate_job>
			<job>
				<id>12345</id>
			</job>
		</certificate_job>
	</task>
</request>

<response>
	<result>
		<data>
			<certificate_job>
				<certificate>
					<partner_order_id>IX-CC-12345</partner_order_id>
					<order_id>9202720</order_id>
					<admin>
						<first>Jon</first>
						<last>Doe</last>
						<phone>+49-0-0</phone>
						<fax>+49-0-0</fax>
						<email>jon.doe@domain.de</email>
						<title>Herr</title>
						<organization>Muster GmbH</organization>
						<address>Musterstrasse 6</address>
						<postal_code>12345</postal_code>
						<city>Musterstadt</city>
						<country>DE</country>
						<state>Bayern</state>
						<id>1</id>
					</admin>
					<technical>
						<first>Jon</first>
						<last>Doe</last>
						<phone>+49-0-0</phone>
						<fax>+49-0-0</fax>
						<email>jon.doe@domain.de</email>
						<title>Herr</title>
						<organization>Muster GmbH</organization>
						<address>Musterstrasse 6</address>
						<postal_code>12345</postal_code>
						<city>Musterstadt</city>
						<country>DE</country>
						<state>Bayern</state>
						<id>1</id>
					</technical>
					<name>domain.de</name>
					<approver_email>admin@domain.de</approver_email>
					<lifetime>12</lifetime>
					<software>APACHE2</software>
					<csr><![CDATA[-----BEGIN CERTIFICATE REQUEST----- ... -----END CERTIFICATE REQUEST-----]]></csr>
					<product>RAPID_SSL</product>
					<sha>SHA2_FULL_CHAIN</sha>
					<expire>2020-10-23 00:00:00</expire>
					<extension/>
					<authentication>
						<method>EMAIL</method>
						<approver_email>admin@domain.de</approver_email>
					</authentication>
					<certificate_transparency_privacy>PUBLIC</certificate_transparency_privacy>
					<created>2019-10-23 00:00:00</created>
				</certificate>
				<job>
					<id>12345</id>
					<owner>
						<user>user</user>
						<context>9</context>
					</owner>
					<updater>
						<user>user</user>
						<context4>9</context>
					</updater>
					<object>domain.de</object>
					<status>DEFFERED</status>
					<sub_status>WF_EMAIL_AUTH</sub_status>
					<created>2019-10-23 16:12:33</created>
					<updated>2019-10-23 17:26:01</updated>
					<type>ssl</type>
					<sub_type>RAPID_SSL</sub_type>
					<action>create</action>
					<execution>2019-10-23 17:25:58</execution>
				</job>
			</certificate_job>
		</data>
		<status>
			<code>S400114</code>
			<text>Certificate order was inquired successfully.</text>
			<type>success</type>
			<object>
				<type>certificate_job</type>
				<value>4297755796</value>
			</object>
		</status>
	</result>
	<stid>20200228-stid</stid>
</response>

Canceling a running job

Running jobs can be terminated via the API as long as they have not yet reached the status SUCCESS or FAILED. Note that the termination of a running request does not take effect until it has been terminated at the CA. Before this, the status CANCELED is displayed for the request.

PUT /job/{id}/_cancel

{
  "stid": "20200228-stid",
  "status": {
    "code": "S300121",
    "text": "The workflow request was canceled successfully.",
    "type": "SUCCESS"
  },
  "object": {
    "type": "ObjectJob",
    "value": "12345"
  }
}

<request>
	<auth>
		<user>USER</user>
		<context>CONTEXT</context>
		<password>PASSWORD</password>
	</auth>
	<task>
		<code>400113</code>
		<certificate_job>
			<job>
				<id>12345</id>
			</job>
		</certificate_job>
	</task>
</request>

<response>
	<result>
		<data/>
		<status>
			<code>S400113</code>
			<text>The request was canceled successfully.</text>
			<type>success</type>
			<object>
				<type>certificate_job</type>
				<value>4297782230</value>
			</object>
		</status>
	</result>
	<stid>20200228-stid</stid>
</response>

Resend validation email

The validation email can be resent using the route POST /job/{id}/_resendApproverEmail or the XML task code 400118.

POST /job/{id}/_resendApproverEmail

{
  "stid": "20200228-stid",
  "status": {
    "code": "S400118",
    "text": "The order for resending was successfully submitted to the CA.",
    "type": "SUCCESS"
  },
  "object": {
    "type": "Certificate_job",
    "value": "12345"
  }
}

<request>
	<auth>
		<user>USER</user>
		<context>CONTEXT</context>
		<password>PASSWORD</password>
	</auth>
	<task>
		<code>400118</code>
		<certificate_job>
			<job>
				<id>12345</id>
			</job>
		</certificate_job>
	</task>
</request>

<response>
	<result>
		<data/>
		<status>
			<code>S400118</code>
			<text>The order for resending was successfully submitted to the CA.</text>
			<type>success</type>
			<object>
				<type>certificate_job</type>
				<value>12345</value>
			</object>
		</status>
	</result>
	<stid>20200228-stid</stid>
</response>