SSL.com API For Certificates

RESTful api for automated and seamless ssl certificate purchasing

SSL Certificate RESTful API Overview

Software developers can now integrate SSL.com certificate purchasing into their process flows. The SSL.com Certificate API provides an open standards interface in the form of REST using the well established http protocol and JSON standards. By adopting well-established standards, the api minimizes the learning curve for the development team and results in faster deployment.

Leveraging this open standard api, developers can automatically purchase and manage their ssl certificates. Developers can access status information, as well as cancel and reprocess existing certificates. Even validations can be handled through the api. Requests and responses are in the form of JSON so several return values can be handled in a single response. And best of all, it's all open standards so developers can be up and running quickly and not be tied into a proprietary api language.

Getting Started

Developers must create an SSL.com Reseller account in order to get the required account_key and secret_key credentials necessary to interface with the api. Once this has been done, please visit the "Dashboard" and at the bottom of the screen under "api login credentials", the account_key and secret_key can be found.

SSL API Developer's Guide

POST /certificates/<version>/create

Create an ssl.com certificate order. Upon successful application, the price (if any) of the ssl certificate will be deducted from reseller account associated with the account number specified in the account_key.

version
1.3
example testing url (test orders)
https://sws-test.sslpki.com/certificates/1.3/create
example production url (live orders)
https://sws.sslpki.com/certificates/1.3/create
method
POST
parameters
(!required items are in bold, optional items are in italics; only a single value is allowed per parameter unless otherwise specified)
account_key
The SWS account key of the reseller.
secret_key
The SWS secret key of the reseller.
product
The product code of the ssl certificate being purchased. Select only one code from the following choices:
100 (for Enterprise EV Multi-domain SSL)
102 (for UCC Multi-domain SSL)
103 (for Enterprise EV SSL)
105 (for Multi-subdomain Wildcard SSL)
106 (for Basic SSL)
107 (for Premium SSL)
200 (for EcoSSL - for select partners only)
201 (for EcoSSL Wildcard - for select partners only)
202 (for EcoSSL UCC - for select partners only)
203 (for EcoSSL EV - for select partners only)
204 (for EcoSSL EV UCC - for select partners only)
period
The number of days the certificate is valid for. Depending on the certificate specified by the 'product' key, different options are available (select only one):
365, 730, 1095, 1461, or 1826 for non EV SSL certs
365 or 730 for EV SSL certs
server_count
Applies only to Wildcard, EV UCC, or UCC. The number of servers the ssl certificate will be installed on. Uses value from initial order if left blank.
server_software
The server software which the ssl certificate is to be installed on.
1 OTHER
2 AOL
3 Apache-ModSSL
4 Apache-SSL (Ben-SSL, not Stronghold)
5 C2Net Stronghold
6 Cisco 3000 Series VPN Concentrator
7 Citrix
8 Cobalt Raq
9 Covalent Server Software
10 Ensim
11 HSphere
12 IBM HTTP Server
13 IBM Internet Connection Server
14 iPlanet
15 Java Web Server (Javasoft / Sun)
16 Lotus Domino
17 Lotus Domino Go!
18 Microsoft IIS 1.x to 4.x
19 Microsoft IIS 5.x to 6.x
20 Microsoft IIS 7.x and later
21 Netscape Enterprise Server
22 Netscape FastTrack
23 Novell Web Server
24 Oracle
25 Plesk
26 Quid Pro Quo
27 R3 SSL Server
28 Raven SSL
29 RedHat Linux
30 SAP Web Application Server
31 Tomcat
32 Website Professional
33 WebStar 4.x and later
34 WebTen (from Tenon)
35 WHM/CPanel
36 Zeus Web Server
37 Nginx
38 Heroku
39 Amazon Load Balancer
other_domains
Applies only to UCC or EV UCC multi-domain certificates. These are the additional domains that will appear in the subject alternative names (SAN) field of the ssl certificate. NOTE: commas and/or whitespace may need to be manually URL-encoded (e.g. %2C for a comma), depending on whether or not the calling environment does this automatically.
domain
Applies only to UCC or EV UCC multi-domain certificates. This is the primary domain that will appear in the common name field of the ssl certificate. If not specified, the common name will be extracted from the certificate signing request (csr).
common_names_flag
Applies only to UCC or EV UCC multi-domain certificates..
  • If omitted, all of the domain names listed in "other_domains" will be included as Common Names in the Subject DN of the resulting SSL Certificate.
  • If 1, there will only be 1 Common Name in the resulting certificate. This will have the value provided by "domain" (so, in this case, "domain" must have a value).
  • If 0, no Common Names will be included in the resulting certificate. Note that all of the domain names listed in "other_domains" will always be included as DNS Name components of the Subject Alternative Name extension in the resulting Multi-domain SSL Certificate or EV Multi-domain SSL Certificate.
csr
Certificate signing request (Base-64 encoded). Opening and closing tags are optional i.e:
-----BEGIN xxxxx-----
and
-----END xxxxx-----
  • Version
    0
  • Subject
    The fields may be in any order (although multiple street addresses, if present, should be in the correct order). note: DirectoryString is a choice of PrintableString, TeletexString, BMPString, UniversalString (ASCII only) or UTF8String.
    MUST include these fields:
    OID description ASN.1 type(s) max length
    2.5.4.3 Common Name (Fully-Qualified Domain Name) DirectoryString 64 chars
    MAY include these fields (all other fields not listed will be ignored):
    OID description ASN.1 type(s) max length
    2.5.4.10 Organization Name DirectoryString 64 chars
    2.5.4.11 Organizational Unit DirectoryString 64 chars
    2.5.4.18 Post Office Box DirectoryString 40 chars
    2.5.4.9 Street Address 1 DirectoryString 128 chars
    2.5.4.9 Street Address 2 DirectoryString 128 chars
    2.5.4.9 Street Address 3 DirectoryString 128 chars
    2.5.4.7 Locality Name DirectoryString 128 chars
    2.5.4.8 State or Province Name DirectoryString 128 chars
    2.5.4.17 Postal Code DirectoryString 40 chars
    2.5.4.6 Country Name (ISO3166 2-character code)
    Subject Public Key Info
    Algorithm OID = rsaEncryption (PKCS#1)
    Size = 512 to 8192 bits
    Attributes
    Any attributes MAY be present, but will be ignored
    Signature Algorithm
    md5WithRSAEncryption (PKCS#1) or sha1WithRSAEncryption (PKCS#1) or sha224WithRSAEncryption (PKCS#1) or sha256WithRSAEncryption (PKCS#1) or sha384WithRSAEncryption (PKCS#1) or sha512WithRSAEncryption (PKCS#1)
organization_name [optional if parsed from csr; ignored for domain validated certificates]
Represents the Organization Name.
organization_unit_name
Represents the Organization Unit Name (eg department name).
post_office_box [required if street_address_1 is missing]
Represents the Post Office Box.
street_address_1 [optional if parsed from csr; ignored for domain validated certificates]
Represents the Street Address 1.
street_address_2
Represents the Street Address 2
street_address_3
Represents the Street Address 3
locality_name [optional if parsed from csr; ignored for domain validated certificates]
Represents the Locality Name (eg city or town name).
state_or_province_name [optional if parsed from csr; ignored for domain validated certificates]
Represents the State or Province Name.
postal_code [optional if parsed from csr; ignored for domain validated certificates]
Represents the Postal Code.
country_name [optional if parsed from csr]
Represents the Country Name (ISO3166 2-character country code).
duns_number
Represents the Dun and Bradstreet number.
company_number
Represents the company registration number.
registered_locality_name
Applies only to EV SSL or EV Multi-domain SSL. Represents the city or town (if any) of jurisdiction in which the company is incorporated or registered.
registered_state_or_province_name
Applies only to EV SSL or EV Multi-domain SSL. Represents the state or province (if any) of jurisdiction in which the company is incorporated or registered.
registered_country_name
Applies only to EV SSL or EV Multi-domain SSL. Represents the Country Name (ISO3166 2-character country code) of jurisdiction in which the company is incorporated or registered.
incorporation_date
Applies only to EV SSL or EV Multi-domain SSL. Represents the date of incorporation of the company (YYYY-MM-DD).
assumed_name
Applies only to EV SSL or EV Multi-domain SSL. Represents the dba (doing business as) or assumed named of the company.
business_category
Represents the business category (or type) of the company or registrant.
b (for Private Organization)
c (for Government Entity)
d (for Business Entity)
email_address
Represents the email address to send the processed ssl certificate to. If this parameter is not specified, then the certificate will be sent to the reseller admin email address. If value 'none' is specified, then the ssl certificate will not be emailed to any email address, but the certificate still can be retrieved via an api call.
contact_email_address
Represents an email address will be the only email address that SSL.com Validation Staff will correspond with during the processing of this order. Otherwise reseller admin email address will be used.
dcv_email_address
Required if 'dcv_methods' is not used. This parameter is kept for legacy purposes. See 'dcv_methods' for the preferred parameter to use. Represents the email address with which to perform Domain Control Validation for this certificate. This will be one email address selected from a number of email address choices. See the documentation below for the dcv_emails API for more information on how to query for these choices.
dcv_methods
Required if preferred key 'dcv_email_address' is not used. This parameter is the preferred parameter between the two and will take priority over 'dcv_email_address'. Represents the domain control validation (dcv) method (or methods if the certificate is UCC or EV UCC). The 3 types of accepted values are the chosen dcv email address, 'file', or 'dns'. For UCC or EV UCC where multiple domains need to be validated, then the submitted value should be a JSON object with each domain as a key and any accepted option as the value. There is no need to specify anything for intranet domains. Example for a UCC certificate: "dcv_methods" : { "www.domain.net" : "admin@domain.net", "yoursite.com" : "file"}
<email address> This is an email address chosen from the dcv emails lookup.
file This option is used for validation via verifying a file over http.
dns This option is used for validation via for verifying a CNAME dns entry.
ca_certificate_id
Overrides SSL.com’s default choice of CA certificate/key to be used to issue this certificate. This functionality is only available by special agreement with SSL.com.
is_customer_validated [ignored for dv certs]
Has the customer been validated according to SSL.com's RA validation guidelines?
y (the host or reseller has validated the customer)
n (SSL.com will perform the validation)
hide_certificate_reference
Hide the certificate reference number in the emailed ssl certificate. By default, the ssl certificate reference number is displayed in the email.
y (hide the certificate reference number in the emailed ssl certificate)
n (default; show the certificate reference number in the emailed ssl certificate)
external_order_number
This identifier is provided for integration with partner systems. If the external system has a record or identifier that needs to associate with this particular ssl certificate order, then the developer provides an external order number or identifier so that the developer can make the association.
sample request
Using the curl command line utility, you can test an api request using something similar to the following:
curl -H "Accept: application/json" -H "Content-type: application/json" -X POST -d "{\"account_key\" : \"xxxxxx\",\"secret_key\" : \"xxxxxxxxx\",\"product\" : \"100\", \"period\" : \"365\", \"server_count\" : \"1\", \"server_software\" : \"15\", \"organization_name\" : \"yoursite\", \"street_address_1\" : \"somewhere st\", \"locality_name\" : \"new york\", \"state_or_province_name\" : \"new york\", \"postal_code\" : \"77777\", \"country_name\" : \"US\", \"duns_number\" : \"1234567\", \"company_number\" : \"yoursite_number\", \"registered_country_name\" : \"US\", \"incorporation_date\" : \"12/12/2000\", \"is_customer_validated\" : \"y\", \"dcv_email_address\" : \"admin@yoursite.com\", \"csr\" : \"-----BEGIN CERTIFICATE REQUEST-----\nMIICvTCCAaUCAQAweDELMAkGA1UEBhMCdXMxDjAMBgNVBAgTBVRleGFzMRAwDgYD\nVQQHEwdIb3VzdG9uMRUwEwYDVQQKEwxZb3VyIENvbXBhbnkxFTATBgNVBAsTDFlv\ndXIgSVQgRGVwdDEZMBcGA1UEAxMQd3d3LnlvdXJzaXRlLmNvbTCCASIwDQYJKoZI\nhvcNAQEBBQADggEPADCCAQoCggEBAKWnrKf35qmU/tBnieUcQmf0xhntGO2YDgAO\nW9J44IAhC1IB715312J28WvoLSSZDuBxqMaLgBbcNyrRFkwbZ+sRbLsjJ24v21Dt\nLE2gMSbr9YSuH0McOBh9sf23tHd2n5rteJn5fVuxc6ak3t9mag2jjD43Blyh3ih7\nADPj0XAk0Gfn+obfmKPMpZwYEhXnJNtWKHzflzAjUjaxbMwMIrvgZcvk/BZZ184z\nYquasNmvJotvptP0RF3J0GhuiYg75BgimMq3YFxFjAnYjRRZ7p8z/DEfTkdZOPHG\nypaz4ny+l8lggyvMOgZD7yanGuVxzlBhpB90INXVDX9+yQ23XHECAwEAAaAAMA0G\nCSqGSIb3DQEBBQUAA4IBAQAwbFXORWmD9ovp4qsxozzUZAKxUTluiTIsO+bK2pXV\nHAhxVkzcVi8nFqzkeAuKRTQ9UZPMjnnjHWOKIghIpiAabSiC0E/0SPR9s3QzJWhV\nOfOpoKYoRnDUh+/SH/Otg4Wid7yKOfdPFK4J8GtnPB2i5Eih0ZOYTTIU2xSmkZ9T\n+LoB7PxOVii8Dq5Nrbbzq8x/WpJfKTackp6nWl2ILcfXM3iGBmLqXPRn5/Uvj767\nrq5mHXD2IakxBAeTci16WqQEVcow3qn1JwLyGOzXuuW/UA2/HJUE4zG+8CQIb3OL\n0Yq26QKt/i5CJv//uZcRZY8VRkPaH090QOr85UfP7Y3D\n-----END CERTIFICATE REQUEST-----\"}" https://sws-test.sslpki.com/certificates/1.3/create
successful response
Upon successful order placement, returns a JSON formatted response containing information about the newly created ssl certificate order:
order_number
This is the order number that should be used when referencing this new order.
order_status
Represents the status of the order. Valid values are:
waiting for domain control validation
waiting for documents
pending validation
validated
issued
revoked
canceled
order_amount
This is the amount (in USD) that was debited from the reseller account.
certificate_url
This is the url where the ssl certificate can be managed or downloaded.
order_receipt_url
This is the url where order receipt is displayed.
smart_seal_url
This is the url where the smart seal can be configured.
validation_documents_url
This is the url where validation documents can be submitted or reviewed for acceptance.
Sample JSON return value for a successful request:
{"order_number" : "abcd1234", "order_status" : "pending validation", "order_amount" : "$49.00", "certificate_url" : "https://www.ssl.com/certificate_orders/abcd1234", "order_receipt_url" : "https://www.ssl.com/orders/abcd1234", "smart_seal_url" : "https://www.ssl.com/smart_seals/abcd1234", "validation_documents_url" : "https://www.ssl.com/validations/abcd1234"}
errors
If order placement is unsuccessful, then the JSON response will include only include the parent key 'errors' and an array of possible errors.
Sample JSON return value for a failed request:
{"errors":{"account_key":["can't be blank"], "secret_key":["can't be blank"], "csr":["can't be blank"], "period":["can't be blank","is invalid","needs to be one of the following: 365, 730, 1095, 1461, 1826"], "server_software":["can't be blank","is invalid", "needs to be one of the following: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37"], "organization_name":["can't be blank"],"post_office_box": ["is required if street_address_1 is not specified"],"street_address_1": ["is required if post_office_box is not specified"],"locality_name": ["can't be blank"],"state_or_province_name":["can't be blank"], "postal_code":["can't be blank"],"product":["can't be blank", "is invalid","needs to one of the following: 100, 101, 102, 103, 104, 105, 106, 107, 200"], "is_customer_validated":["is invalid","can't be blank"]}}

POST /certificates/<version>/dcv_emails

Query for a list of email address choices (click here to see the possible choices) that can be used in validating the ownership or control of a domain name. One of these email addresses can then be used in the dcv_email_address or dcv_methods parameter when placing an order. See 'POST /certificates/<version>/create' above for more details on placing ssl.com certificate orders. through the api.

version
1.3
example testing url (test orders)
https://sws-test.sslpki.com/certificates/1.3/dcv_emails
example production url (live orders)
https://sws.sslpki.com/certificates/1.3/dcv_emails
method
POST
parameters
(!required items are in bold, optional items are in italics; only a single value is allowed per parameter unless otherwise specified)
account_key
The SWS account key of the reseller.
secret_key
The SWS secret key of the reseller.
domain_name
Get the list of email address choices for this domain name which typically will be the domain name for which the certificate will be issued to.
sample request
Using the curl command line utility, you can test an api request using something similar to the following:
curl -H "Accept: application/json" -H "Content-type: application/json" -X POST -d "{\"account_key\" : \"xxxxxx\",\"secret_key\" : \"xxxxxxxxx\", \"domain_name\" : \"yoursite.com\"}" https://sws-test.sslpki.com/certificates/1.3/dcv_emails
successful response
Returns a JSON formatted response containing an array of email address choices under the single parent key 'email_addresses'.
email_addresses
This is an array of email address choices that can satisfy proof of domain control.
Sample JSON return value for a successful request:
{"email_addresses":["webmaster@ssl.com", "postmaster@ssl.com","hostmaster@ssl.com","administrator@ssl.com", "admin@ssl.com","webmaster@certs.ssl.com","postmaster@certs.ssl.com", "hostmaster@certs.ssl.com","administrator@certs.ssl.com", "admin@certs.ssl.com"]}
errors
If a query is unsuccessful, then the JSON response will include only include the parent key 'errors' and an array of possible errors. A sample JSON return value for a failed query would look like:
{"errors":{"domain_name":["%&* is not a valid domain name"]}}

POST /certificates/<version>/dcv_email_resend

Resend dcv email from the list of email address choices (click here to see the possible choices) used in validating the ownership or control of a domain name.

version
1.3
example testing url (test orders)
https://sws-test.sslpki.com/certificates/1.3/dcv_email_resend
example production url (live orders)
https://sws.sslpki.com/certificates/1.3/dcv_email_resend
method
POST
parameters
(!required items are in bold, optional items are in italics; only a single value is allowed per parameter unless otherwise specified)
account_key
The SWS account key of the reseller.
secret_key
The SWS secret key of the reseller.
ref
The reference number of the certificate order that we want to resend the dcv email for.
email_address
Resend the validation email to this email address. If this parameter is left blank, then the validation email will be resent to the original email address specified during order placement. The value must be one of the possible choices outlined here.
sample request
Using the curl command line utility, you can test an api request using something similar to the following:
curl -H "Accept: application/json" -H "Content-type: application/json" -X POST -d "{\"account_key\" : \"xxxxxx\",\"secret_key\" : \"xxxxxxxxx\", \"email_address\" : \"admin@yoursite.com\", \"ref\" : \"co-xxxxxx\"}" https://sws-test.sslpki.com/certificates/1.3/dcv_email_resend
successful response
Returns a JSON formatted response containing the time and date when the email was sent under the key 'sent_at'.
sent_at
This is the time and date when the email was resent.
Sample JSON return value for a successful request:
{"sent_at":["2012-01-22 00:36:20"]}
errors
If a query is unsuccessful, then the JSON response will include only include the parent key 'errors' and an array of possible errors. A sample JSON return value for a failed query would look like:
{"errors":{"domain_name":["%&* is not a valid domain name"]}}

POST /certificates/<version>/retrieve

Retrieve the certificate or check the status of a certificate order placed earlier. See 'POST /certificates/<version>/create' above for more details on placing ssl.com certificate orders" through the api.

version
1.3
example testing url (test orders)
https://sws-test.sslpki.com/certificates/1.3/retrieve
example production url (live orders)
https://sws.sslpki.com/certificates/1.3/retrieve
method
POST
parameters
(!required items are in bold, optional items are in italics; only a single value is allowed per parameter unless otherwise specified)
account_key
The SWS account key of the reseller.
secret_key
The SWS secret key of the reseller.
ref
The ref number of the ssl.com certificate order that we are querying about or want to retrieve. The ref number normally has the format co-xxxxxxx where x is any hex value.
query_type
The return value of this retrieval. Must be one of the following:
order_status for order status inquiry only
all_certificates for the entire certificate chain including end, root and intermediate certificates if ready
end_certificate for the end certificate only if ready (no root or intermediate certificates)
ca_bundle for the root and intermediate certificates (no end certificate)
response_type
How should the return value be packaged:
zip - zip file format (query_type must be 'all_certificates')
netscape - Netscape certificate sequence format (query_type must be 'all_certificates')
pkcs7 - PKCS7 format (query_type must be 'all_certificates')
individually_encoded - individually encoded format
response_encoding
How should the certificate(s) be encoded:
base64 - base64 encoding
binary - binary encoding (query_type must be 'all_certificates' and response_type must be 'zip' or 'pkcs7')
show_validity_period
Return the validity period. Value can be any of the following: Y,N,y,n
show_domains
Show all domains on this certificate. Each domain is a key, and it's validation status is the value. Can be any of the following: Y,N,y,n
Using the curl command line utility, you can test an api request using something similar to the following:
curl -H "Accept: application/json" -H "Content-type: application/json" -X POST -d "{\"account_key\" : \"xxxxxx\",\"secret_key\" : \"xxxxxxxx\", \"ref\" : \"co-xxxxxxx\", \"query_type\" : \"status\"}" https://sws-test.sslpki.com/certificates/1.3/retrieve
successful response
Upon successful order retrieval, returns a JSON formatted response containing status information and, if requested, the actual certificate based on the the ssl certificate ref number:
order_status
Represents the status of the order. Valid values are:
waiting for domain control validation
waiting for documents
pending validation
validated
issued
revoked
canceled
certificate
Base64 encoded (and then url encoded) end-entity certificate. This key is only present when response_type is set to individually_encoded and query_type is set to all_certificates or end_certificate.
zip_file
Base64 encoded (and then url encoded) zip file. This key is only present when response_type is set to zip.
ca_bundle
Base64 encoded (and then url encoded) end-entity certificate. This key is only present when response_type is set to individually_encoded. If there is more than 1 certificate, an array of encoded certificates will be returned.
domains
All domains associated with this certificate if show_domains was set to Y or y. Each domain is a key, and it's validation status is the value.
validity_period
Number of days this certificate is effective if show_domains is set to Y or y.
Sample JSON return value for a successful request:
{"order_status":"waiting for domain control validation"}
errors
If a query is unsuccessful, then the JSON response will include only include the parent key 'errors' and an array of possible errors. A sample JSON return value for a failed request would look like:
{"errors":{"account_key":["can't be blank"],"secret_key":["can't be blank"], "ref":["can't be blank"],"query_type":["can't be blank", "needs to be one of the following: order_status, end_certificate, all_certificates, ca_bundle"]}}

POST /certificates/<version>/reprocess

Reprocess or redo an existing certificate order that has been issued already.

version
1.3
example testing url (test orders)
https://sws-test.sslpki.com/certificates/1.3/reprocess
example production url (live orders)
https://sws.sslpki.com/certificates/1.3/reprocess
method
POST
parameters
(!required items are in bold, optional items are in italics; only a single value is allowed per parameter unless otherwise specified)
account_key
The SWS account key of the reseller.
secret_key
The SWS secret key of the reseller.
ref
The reference number of the certificate order being reprocessed.
server_count
Applies only to Wildcard, EV UCC, or UCC. The number of servers the ssl certificate will be installed on. Uses value from initial order if left blank.
server_software
The server software which the ssl certificate is to be installed on. Uses value from initial order if left blank.
1 OTHER
2 AOL
3 Apache-ModSSL
4 Apache-SSL (Ben-SSL, not Stronghold)
5 C2Net Stronghold
6 Cisco 3000 Series VPN Concentrator
7 Citrix
8 Cobalt Raq
9 Covalent Server Software
10 Ensim
11 HSphere
12 IBM HTTP Server
13 IBM Internet Connection Server
14 iPlanet
15 Java Web Server (Javasoft / Sun)
16 Lotus Domino
17 Lotus Domino Go!
18 Microsoft IIS 1.x to 4.x
19 Microsoft IIS 5.x to 6.x
20 Microsoft IIS 7.x and later
21 Netscape Enterprise Server
22 Netscape FastTrack
23 Novell Web Server
24 Oracle
25 Plesk
26 Quid Pro Quo
27 R3 SSL Server
28 Raven SSL
29 RedHat Linux
30 SAP Web Application Server
31 Tomcat
32 Website Professional
33 WebStar 4.x and later
34 WebTen (from Tenon)
35 WHM/CPanel
36 Zeus Web Server
37 Nginx
38 Heroku
39 Amazon Load Balancer
other_domains
Applies only to UCC or EV UCC multi-domain certificates. These are the additional domains that will appear in the subject alternative names (SAN) field of the ssl certificate. NOTE: commas and/or whitespace may need to be manually URL-encoded (e.g. %2C for a comma), depending on whether or not the calling environment does this automatically.
domain
Applies only to UCC or EV UCC multi-domain certificates. This is the primary domain that will appear in the common name field of the ssl certificate. If not specified, the common name will be extracted from the certificate signing request (csr).
common_names_flag
Applies only to UCC or EV UCC multi-domain certificates..
  • If omitted, all of the domain names listed in "other_domains" will be included as Common Names in the Subject DN of the resulting SSL Certificate.
  • If 1, there will only be 1 Common Name in the resulting certificate. This will have the value provided by "domain" (so, in this case, "domain" must have a value).
  • If 0, no Common Names will be included in the resulting certificate. Note that all of the domain names listed in "other_domains" will always be included as DNS Name components of the Subject Alternative Name extension in the resulting Multi-domain SSL Certificate or EV Multi-domain SSL Certificate.
csr
Certificate signing request (Base-64 encoded). Opening and closing tags are optional i.e:
-----BEGIN xxxxx-----
and
-----END xxxxx-----
organization_name [optional if parsed from csr; ignored for domain validated certificates]
Represents the Organization Name.
organization_unit_name
Represents the Organization Unit Name (eg department name).
post_office_box [required if street_address_1 is missing]
Represents the Post Office Box.
street_address_1 [optional if parsed from csr; ignored for domain validated certificates]
Represents the Street Address 1.
street_address_2
Represents the Street Address 2
street_address_3
Represents the Street Address 3
locality_name [optional if parsed from csr; ignored for domain validated certificates]
Represents the Locality Name (eg city or town name).
state_or_province_name [optional if parsed from csr; ignored for domain validated certificates]
Represents the State or Province Name.
postal_code [optional if parsed from csr; ignored for domain validated certificates]
Represents the Postal Code.
country_name [optional if parsed from csr]
Represents the Country Name (ISO3166 2-character country code).
duns_number
Represents the Dun and Bradstreet number.
company_number
Represents the company registration number.
registered_locality_name
Applies only to EV SSL or EV Multi-domain SSL. Represents the city or town (if any) of jurisdiction in which the company is incorporated or registered.
registered_state_or_province_name
Applies only to EV SSL or EV Multi-domain SSL. Represents the state or province (if any) of jurisdiction in which the company is incorporated or registered.
registered_country_name
Applies only to EV SSL or EV Multi-domain SSL. Represents the Country Name (ISO3166 2-character country code) of jurisdiction in which the company is incorporated or registered.
incorporation_date
Applies only to EV SSL or EV Multi-domain SSL. Represents the date of incorporation of the company (YYYY-MM-DD).
assumed_name
Applies only to EV SSL or EV Multi-domain SSL. Represents the dba (doing business as) or assumed named of the company.
business_category
Represents the business category (or type) of the company or registrant.
b (for Private Organization)
c (for Government Entity)
d (for Business Entity)
email_address
Represents the email address to send the processed ssl certificate to. If this parameter is not specified, then the certificate will be sent to the reseller admin email address. If value 'none' is specified, then the ssl certificate will not be emailed to any email address, but the certificate still can be retrieved via an api call.
contact_email_address
Represents an email address will be the only email address that SSL.com Validation Staff will correspond with during the processing of this order. Otherwise reseller admin email address will be used.
dcv_methods
Represents the domain control validation (dcv) method (or methods if the certificate is UCC or EV UCC). The 3 types of accepted values are the chosen dcv email address, 'file', or 'dns'. For UCC or EV UCC where multiple domains need to be validated, then the submitted value should be a JSON object with each domain as a key and any accepted option as the value. There is no need to specify anything for intranet domains. Example for a UCC certificate: "dcv_methods" : { "www.domain.net" : "admin@domain.net", "yoursite.com" : "file"}
<email address> This is an email address chosen from the dcv emails lookup.
file This option is used for validation via verifying a file over http.
dns This option is used for validation via verifying a CNAME dns entry.
ca_certificate_id
Overrides SSL.com’s default choice of CA certificate/key to be used to issue this certificate. This functionality is only available by special agreement with SSL.com.
hide_certificate_reference
Hide the certificate reference number in the emailed ssl certificate. By default, the ssl certificate reference number is displayed in the email.
y (hide the certificate reference number in the emailed ssl certificate)
n (default; show the certificate reference number in the emailed ssl certificate)
external_order_number
This identifier is provided for integration with partner systems. If the external system has a record or identifier that needs to associate with this particular ssl certificate order, then the developer provides an external order number or identifier so that the developer can make the association.
sample request
Using the curl command line utility, you can test an api request using something similar to the following:
curl -H "Accept: application/json" -H "Content-type: application/json" -X POST -d "{\"account_key\" : \"xxxxxx\",\"secret_key\" : \"xxxxxxxxx\", \"organization_name\" : \"yoursite\", \"street_address_1\" : \"somewhere st\", \"locality_name\" : \"new york\", \"state_or_province_name\" : \"new york\", \"postal_code\" : \"77777\", \"country_name\" : \"US\", \"duns_number\" : \"1234567\", \"company_number\" : \"yoursite_number\", \"registered_country_name\" : \"US\", \"incorporation_date\" : \"12/12/2000\", \"dcv_methods\" : \"admin@yoursite.com\", \"csr\" : \"-----BEGIN CERTIFICATE REQUEST-----\nMIICvTCCAaUCAQAweDELMAkGA1UEBhMCdXMxDjAMBgNVBAgTBVRleGFzMRAwDgYD\nVQQHEwdIb3VzdG9uMRUwEwYDVQQKEwxZb3VyIENvbXBhbnkxFTATBgNVBAsTDFlv\ndXIgSVQgRGVwdDEZMBcGA1UEAxMQd3d3LnlvdXJzaXRlLmNvbTCCASIwDQYJKoZI\nhvcNAQEBBQADggEPADCCAQoCggEBAKWnrKf35qmU/tBnieUcQmf0xhntGO2YDgAO\nW9J44IAhC1IB715312J28WvoLSSZDuBxqMaLgBbcNyrRFkwbZ+sRbLsjJ24v21Dt\nLE2gMSbr9YSuH0McOBh9sf23tHd2n5rteJn5fVuxc6ak3t9mag2jjD43Blyh3ih7\nADPj0XAk0Gfn+obfmKPMpZwYEhXnJNtWKHzflzAjUjaxbMwMIrvgZcvk/BZZ184z\nYquasNmvJotvptP0RF3J0GhuiYg75BgimMq3YFxFjAnYjRRZ7p8z/DEfTkdZOPHG\nypaz4ny+l8lggyvMOgZD7yanGuVxzlBhpB90INXVDX9+yQ23XHECAwEAAaAAMA0G\nCSqGSIb3DQEBBQUAA4IBAQAwbFXORWmD9ovp4qsxozzUZAKxUTluiTIsO+bK2pXV\nHAhxVkzcVi8nFqzkeAuKRTQ9UZPMjnnjHWOKIghIpiAabSiC0E/0SPR9s3QzJWhV\nOfOpoKYoRnDUh+/SH/Otg4Wid7yKOfdPFK4J8GtnPB2i5Eih0ZOYTTIU2xSmkZ9T\n+LoB7PxOVii8Dq5Nrbbzq8x/WpJfKTackp6nWl2ILcfXM3iGBmLqXPRn5/Uvj767\nrq5mHXD2IakxBAeTci16WqQEVcow3qn1JwLyGOzXuuW/UA2/HJUE4zG+8CQIb3OL\n0Yq26QKt/i5CJv//uZcRZY8VRkPaH090QOr85UfP7Y3D\n-----END CERTIFICATE REQUEST-----\"}" https://sws-test.sslpki.com/certificates/1.3/reprocess
successful response
Upon successful order placement, returns a JSON formatted response containing information about the newly created ssl certificate order:
order_number
This is the order number that should be used when referencing this new order.
order_status
Represents the status of the order. Valid values are:
waiting for domain control validation
waiting for documents
pending validation
validated
issued
revoked
canceled
order_amount
This is the amount (in USD) that was debited from the reseller account.
certificate_url
This is the url where the ssl certificate can be managed or downloaded.
order_receipt_url
This is the url where order receipt is displayed.
smart_seal_url
This is the url where the smart seal can be configured.
validation_documents_url
This is the url where validation documents can be submitted or reviewed for acceptance.
Sample JSON return value for a successful request:
{"order_number" : "abcd1234", "order_status" : "pending validation", "order_amount" : "$49.00", "certificate_url" : "https://www.ssl.com/certificate_orders/abcd1234", "order_receipt_url" : "https://www.ssl.com/orders/abcd1234", "smart_seal_url" : "https://www.ssl.com/smart_seals/abcd1234", "validation_documents_url" : "https://www.ssl.com/validations/abcd1234"}
errors
If order placement is unsuccessful, then the JSON response will include only include the parent key 'errors' and an array of possible errors.
Sample JSON return value for a failed request:
{"errors":{"account_key":["can't be blank"], "secret_key":["can't be blank"], "csr":["can't be blank"], "ref":["can't be blank"], "organization_name":["can't be blank"],"post_office_box": ["is required if street_address_1 is not specified"],"street_address_1": ["is required if post_office_box is not specified"],"locality_name": ["can't be blank"],"state_or_province_name":["can't be blank"], "postal_code":["can't be blank"]}}