Request

Endpoint: RequestAndCollectSMIME

https://secure.trust-provider.com/products/download/RequestAndCollectSMIME

Use the POST method for this endpoint.

Submit parameters in the x-www-form-urlencoded format.

Request parameters

The following table displays the required, optional, and conditional parameters.

Parameter Requirement Type Max.Length Description

Parameter	Requirement	Type	Max.Length	Description
`loginName`	required	string	64 chars	Your account username. This value is case sensitive.
`loginPassword`	required	string	128 chars	Your account password. This value is case sensitive.
`orderNumber`	conditional	string	128 chars	The order number of a previously ordered S/MIME certificate, for which you want to provide the CSR and/or collect the certificate. Required unless `collectionCode` is provided.
`collectionCode`	conditional	string	16 chars	The S/MIME product collection code. Obtain the code by passing the `showCollectionCode=Y` parameter in the certificate request using `AutoApplyOrder`. If specified, the `loginName`, `loginPassword` and `orderNumber` can be omitted.
`csr`	optional	string	32767 chars	The PKCS#10 and Base64-encoded certificate signing request, with or without the header and footer `-----BEGIN xxxxx----- and -----END xxxxx-----`. Use this parameter if the CSR was not provided earlier, otherwise an error will occur. If the Microsoft certificate template extension is provided in the CSR, it is automatically extracted for inclusion in the certificate.
`returnCertificate`	optional	char	1 char	Specifies whether to initiate the certificate issuance process in case all conditions for issuance have been met.
`queryType`	required	integer		Specifies the type of query. The allowed values are: `0` — Return status only. `1` — Return status, certificate data, and intermediates/roots if ready for collection. `2` — Return status and certificate only (no intermediates/roots) (crt). `3` — Return status and intermediates/roots only (cabundle).
`responseType`	optional	integer		Specifies the format of the returned certificate data. The allowed values are: `1` — Netscape Certificate Sequence. `queryType` must be `1`. `2` — PKCS7. `queryType` must be `1`. `3` — Individually encoded. `4` — CMMF. `queryType` must be `1`. If omitted, the value defaults to `3`.
`responseEncoding`	optional	integer		Specifies the encoding of the returned certificate data. The allowed values are: `0` — Base64-encoded. `1` — Binary encoded. `queryType` must be `1` and `responseType` must be `2`. `2` — Javascript variable declarations (`g_ccc` contains the Base64 structure requested by `responseType`; `g_errorCode` contains the status code). If omitted, the value defaults to `0`.
`responseMimeType`	optional	string	255 chars	Specifies a MIME type, for example, `application/x-x509-user-cert`. For `responseEncoding=2`, the default value is `text/javascript` if this parameter is omitted. Otherwise, the value is `text/plain`.
`showValidityPeriod`	optional	char	1 char	Specifies the validity period of the certificate. The allowed values are: `Y` — Show the validity period. `N` — Do not show the validity period. If omitted, the value defaults to `N`. Applicable only for `responseEncoding=0`.

loginName

required

string

64 chars

Your account username.

This value is case sensitive.

loginPassword

required

string

128 chars

Your account password.

This value is case sensitive.

orderNumber

conditional

string

128 chars

The order number of a previously ordered S/MIME certificate, for which you want to provide the CSR and/or collect the certificate.

Required unless collectionCode is provided.

collectionCode

conditional

string

16 chars

The S/MIME product collection code. Obtain the code by passing the showCollectionCode=Y parameter in the certificate request using AutoApplyOrder.

If specified, the loginName, loginPassword and orderNumber can be omitted.

csr

optional

string

32767 chars

The PKCS#10 and Base64-encoded certificate signing request, with or without the header and footer -----BEGIN xxxxx----- and -----END xxxxx-----.

Use this parameter if the CSR was not provided earlier, otherwise an error will occur.

If the Microsoft certificate template extension is provided in the CSR, it is automatically extracted for inclusion in the certificate.

returnCertificate

optional

char

1 char

Specifies whether to initiate the certificate issuance process in case all conditions for issuance have been met.

queryType

required

integer

Specifies the type of query.

The allowed values are:

0 — Return status only.
1 — Return status, certificate data, and intermediates/roots if ready for collection.
2 — Return status and certificate only (no intermediates/roots) (crt).
3 — Return status and intermediates/roots only (cabundle).

responseType

optional

integer

Specifies the format of the returned certificate data.

The allowed values are:

1 — Netscape Certificate Sequence. queryType must be 1.
2 — PKCS7. queryType must be 1.
3 — Individually encoded.
4 — CMMF. queryType must be 1.

If omitted, the value defaults to 3.

responseEncoding

optional

integer

Specifies the encoding of the returned certificate data.

The allowed values are:

0 — Base64-encoded.
1 — Binary encoded. queryType must be 1 and responseType must be 2.
2 — Javascript variable declarations (g_ccc contains the Base64 structure requested by responseType; g_errorCode contains the status code).

If omitted, the value defaults to 0.

responseMimeType

optional

string

255 chars

Specifies a MIME type, for example, application/x-x509-user-cert.

For responseEncoding=2, the default value is text/javascript if this parameter is omitted. Otherwise, the value is text/plain.

showValidityPeriod

optional

char

1 char

Specifies the validity period of the certificate.

The allowed values are:

Y — Show the validity period.
N — Do not show the validity period.

If omitted, the value defaults to N.

Applicable only for responseEncoding=0.

Sample request

curl --location 'https://secure.trust-provider.com/products/download/RequestAndCollectSMIME' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'loginName=login_name' \
--data-urlencode 'loginPassword=login_password' \
--data-urlencode 'orderNumber=order_number' \
--data-urlencode 'queryType=1' \
--data-urlencode 'returnCertificate=Y' \
--data-urlencode 'responseType=2' \
--data-urlencode 'responseEncoding=0' \
--data-urlencode 'responseMimeType=application/x-x509-user-cert'

Response

The request is successful when the server returns a response with the status code is greater than or equal to 0.

2 — Certificates attached.
1 — Certificates available.
0 — Request accepted and being processed by Sectigo.

Any status code less than 0 indicates an error condition.

The list of codes and their descriptions can be found in Error codes.

If responseEncoding=2, the response is returned as JavaScript variable declarations.

If responseEncoding=1, the certificate(s) are available, and no error occurs, the output will consist simply of the requested binary structure.

If responseEncoding=0, the output will be formatted like one of the following:

If the status code is greater than 0, the output will be displayed as the value of responseMimeType or text/plain.
If the status code is less than or equal to 0, the output will be displayed as the text/plain.

The first line of the response represents a status code.

If the status code is less than 0, the second line is a textual representation of an error message.

If the status code is greater than 0 and showValidityPeriod=Y, the second line is the certificate validity period in the format not before DD/MM/YYYY and not after DD/MM/YYYY with a space between the dates.

14/05/2013 13/05/2014

Certificates issued by Sectigo always have a 'not before' time of 00:00:00 GMT and a 'not after' time of 23:59:59 GMT.

If the status code equals 2, the response contains the encoded certificate(s):

----- BEGIN CERTIFICATE -----
Encoded Root Certificate
----- END CERTIFICATE -----
----- BEGIN CERTIFICATE -----
Encoded Intermediate Certificate
----- END CERTIFICATE -----
----- BEGIN CERTIFICATE -----
Encoded End Entity Certificate
---- END CERTIFICATE -----

Sample success response

Success response with the code 0.

Sample error response

-20
The CSR has been rejected!

Error codes

The following table outlines error responses returned by the RequestAndCollectSMIME API endpoint.

Each error response consists of an errorCode and an errorMessage indicating why the request failed.

Error Code Error Message Description

Error Code	Error Message	Description
`-1`	`Request was not made over https!`	The request must use `HTTPS` protocol.
`-2`	`Unrecognised argument!`	The provided argument is not recognized.
`-3`	`The 'xxx' argument is missing!`	The required argument is missing from the request.
`-4`	`The value of the 'xxxx' argument is invalid!`	The argument value does not meet validation requirements.
`-13`	`The CSR uses an unsupported key size`	The key size in the CSR is not supported.
`-14`	`An unknown error occurred!`	An unknown error occurred.
`-16`	`Incorrect login details, account is locked, password has expired or your source IP is blocked.`	Authentication has failed due to one of the specified reasons. Verify your login credentials or check account restrictions.
`-17`	`Request used GET rather than POST!`	The request method should be `POST`.
`-18`	`A CSR has already been provided.`	The CSR has already been submitted for this request.
`-20`	`The CSR has been rejected!`	The provided CSR has been rejected.
`-21`	`The certificate has been revoked!`	The certificate cannot be collected because it has been revoked.
`-22`	`Still awaiting payment!`	The certificate cannot be collected because payment is still pending.
`-153`	`Unsupported product type!`	The specified product type is not supported.
`-154`	`Email verification not yet completed!`	The email verification process has not been completed.

-1

Request was not made over https!

The request must use HTTPS protocol.

-2

Unrecognised argument!

The provided argument is not recognized.

-3

The 'xxx' argument is missing!

The required argument is missing from the request.

-4

The value of the 'xxxx' argument is invalid!

The argument value does not meet validation requirements.

-13

The CSR uses an unsupported key size

The key size in the CSR is not supported.

-14

An unknown error occurred!

An unknown error occurred.

-16

Incorrect login details, account is locked, password has expired or your source IP is blocked.

Authentication has failed due to one of the specified reasons. Verify your login credentials or check account restrictions.

-17

Request used GET rather than POST!

The request method should be POST.

-18

A CSR has already been provided.

The CSR has already been submitted for this request.

-20

The CSR has been rejected!

The provided CSR has been rejected.

-21

The certificate has been revoked!

The certificate cannot be collected because it has been revoked.

-22

Still awaiting payment!

The certificate cannot be collected because payment is still pending.

-153

Unsupported product type!

The specified product type is not supported.

-154

Email verification not yet completed!

The email verification process has not been completed.