SSL.com API For Certificates

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.

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. For information purposes only.

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 [optional if parsed from csr; ignored for domain validated certificates]

Represents the Organization Name.

organization_unit

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 [optional if parsed from csr; ignored for domain validated certificates]

Represents the Locality Name (eg city or town name).

state_or_province [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

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\" : \"yoursite\", \"street_address_1\" : \"somewhere st\", \"locality\" : \"new york\", \"state_or_province\" : \"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

pending issuance

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://secure.ssl.com/certificate_orders/abcd1234", "order_receipt_url" : "https://secure.ssl.com/orders/abcd1234", "smart_seal_url" : "https://secure.ssl.com/smart_seals/abcd1234", "validation_documents_url" : "https://secure.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": ["can't be blank"],"state_or_province":["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

pending issuance

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 [optional if parsed from csr; ignored for domain validated certificates]

Represents the Organization Name.

organization_unit

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 [optional if parsed from csr; ignored for domain validated certificates]

Represents the Locality Name (eg city or town name).

state_or_province [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\" : \"yoursite\", \"street_address_1\" : \"somewhere st\", \"locality\" : \"new york\", \"state_or_province\" : \"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

pending issuance

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://secure.ssl.com/certificate_orders/abcd1234", "order_receipt_url" : "https://secure.ssl.com/orders/abcd1234", "smart_seal_url" : "https://secure.ssl.com/smart_seals/abcd1234", "validation_documents_url" : "https://secure.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":["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": ["can't be blank"],"state_or_province":["can't be blank"], "postal_code":["can't be blank"]}}