Request

Endpoint: !AutoReplaceMC

https://secure.trust-provider.com/products/!AutoReplaceMC

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

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

required

string

The order number of a certificate to replace, ordered previously using AutoApplyOrder.

DomainNames

optional

string

32767 chars

The comma-separated or whitespace-separated list of domain names.

Commas and/or whitespace may need to be manually URL-encoded (for example, %2C for a comma), depending on whether or not the calling environment does this automatically.

csr

optional

string

32767 chars

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

If this parameter is omitted, the CSR from the original order will be used instead.

For more information, see CSR parameter structure.

markLogo

optional

string

32767 chars

The Base64 URL-encoded trademark logo.

TrademarkCountryName

optional

string

2 chars

(VMC only) The country name in ISO 3166 two-character country code.

TrademarkOffice

optional

string

255 chars

(VMC only) A TrademarkOffice is a recognized government authority responsible for registering and managing trademarks.

TrademarkIdentifier

optional

string

255 chars

(VMC only) The registration number issued by the trademark office, which is used by the Certificate Authority (CA) to verify the mark.

LogoPriorUseDomainName

optional

string

255 chars

(CMC only) One of the domain names listed in domainNames, which is the proof of prior use of the Mark Logo.

organizationName

optional

string

64 chars

The organization name.

organizationalUnitName

optional

string

64 chars

The organizational unit name.

postOfficeBox

optional

string

40 chars

The organization post office box.

streetAddress1

optional

string

128 chars

The street address where the organization operates.

streetAddress2

optional

string

128 chars

The second part of the company’s street address (if necessary).

streetAddress3

optional

string

128 chars

The third part of the company’s street address (if necessary).

localityName

optional

string

128 chars

The city in which the organization operates.

stateOrProvinceName

optional

string

128 chars

The state or province in which the organization operates.

postalCode

optional

string

128 chars

The company’s postal code.

countryName

optional

string

2 chars

The company’s country name.

dunsNumber

optional

string

20 chars

A unique nine-digit identifier for businesses, provided by the company Dun & Bradstreet.

companyNumber

optional

string

64 chars

The company registration number.

joiLocalityName

optional

string

128 chars

The jurisdiction of the city in which the organization operates.

joiStateOrProvinceName

optional

string

128 chars

The jurisdiction of the state or province in which the organization operates.

joiCountryName

optional

string

2 chars

The jurisdiction of the country in which the company operates.

assumedName

optional

string

64 chars

An optional name under which the organization operates that is different from its legal name. This is a so-called DBA (doing business as) name for the company (if any).

dateOfIncorporation

optional

string

10 chars

The date of incorporation (YYYY-MM-DD) of the company. This is useful information for validation purposes.

dcvEmailAddresses

conditional

string

32767 chars

The list of DCV email addresses.

A comma or white-space-separated list of DCV email addresses to be used to perform Domain Control Validation for each domain in this certificate.

The order in which these email addresses are listed must be exactly the same as the order of the domain names in the certificate request. For more information, see the preceding domainNames parameter.

Alternative DCV mechanisms are now available. For more information, see Domain Control Validation.

You can pass the following values for each domain:

  • HTTPCSRHASH

  • HTTPSCSRHASH

  • CNAMECSRHASH

You can use one of the following magic tokens if all the domains in the order are to be set to the same alternative DCV method:

  • ALLHTTPCSRHASH

  • ALLHTTPSCSRHASH

  • ALLCNAMECSRHASH

The magic token must be the only value passed to the parameter for it to work.

If this parameter is specified, validationTokens is not required.

validationTokens

conditional

string

32767 chars

The list of validation tokens.

The comma or white-space-separated list of DCV email addresses to be used to perform Domain Control Validation for each domain in this certificate. The order in which these email addresses are listed must be exactly the same as the order of the domain names in the certificate request. For more information, see the preceding domainNames parameter.

Alternative DCV mechanisms are now available. For more information, see Domain Control Validation.

The allowed values for each domain:

  • HTTPCSRHASH

  • HTTPSCSRHASH

  • CNAMECSRHASH

The allowed magic tokens if all the domains in the order are to be set to the same alternative DCV method:

  • ALLHTTPCSRHASH

  • ALLHTTPSCSRHASH

  • ALLCNAMECSRHASH

The magic token must be the only value passed to the parameter for it to work.

If this parameter is specified, dcvEmailAddresses is not required.

foreignOrderNumber

optional

char

64 chars

The identifier for the order.

This identifier can be returned by some of our other APIs to aid in integration with partner systems. If a foreignOrderNumber has been assigned to this order on a previous occasion, it will be updated with this new value.

checkFONIsUnique

optional

char

1 char

Specifies whether to check uniqueness of the foreignOrderNumber parameter.

The allowed values are:

  • Y — The foreignOrderNumber parameter (if specified) must not have already been used for any order placed by this account.

  • N — No check of uniqueness is performed for the foreignOrderNumber parameter.

responseFormat

optional

char

1 char

Specifies the response format.

The allowed values are:

  • 0 — Newline-delimited parameters.

  • 1 — URL-encoded parameters.

If omitted, the value defaults to 0.

appRepForename

optional

string

64 chars

The applicant representative’s name which is used for a callback.

This parameter is required when Sectigo performs the organizational callback.

appRepSurname

optional

string

64 chars

The applicant representative’s surname which is used for a callback.

This parameter is required when Sectigo performs the organizational callback.

appRepEmailAddress

optional

string

255 chars

The applicant representative’s email address which is used for a callback.

This parameter is required when Sectigo performs the organizational callback.

appRepTelephone

optional

string

32 chars

The applicant representative’s phone number which is used for a callback.

This parameter is required when Sectigo performs the organizational callback.

appRepTitle

optional

string

64 chars

The applicant representative’s title which is used for a callback.

appRepFax

optional

string

32 chars

The applicant representative’s fax number which is used for a callback.

appRepOrganizationName

optional

string

255 chars

The applicant representative’s organization name.

Do not specify this field unless the applicant representative’s organization name or address details are different from the organization name or address details that have been requested to appear in the certificate.

appRepOrganizationalUnitName

conditional

string

64 chars

The applicant representative’s organizational unit name.

If appRepOrganizationName is not specified, this parameter will be ignored.

appRepStreetAddress1

conditional

string

128 chars

The applicant representative’s street address.

If appRepOrganizationName is not specified, this parameter will be ignored.

appRepStreetAddress2

conditional

string

128 chars

The second part of the applicant representative’s street address (if necessary).

If appRepOrganizationName is not specified, this parameter will be ignored.

appRepStreetAddress3

conditional

string

128 chars

The third part of the applicant representative’s street address (if necessary).

If appRepOrganizationName is not specified, this parameter will be ignored.

appRepPostOfficeBox

conditional

string

128 chars

The applicant representative’s post office box.

If appRepOrganizationName is not specified, this parameter will be ignored.

appRepLocalityName

conditional

string

128 chars

The city in which the applicant representative operates.

If appRepOrganizationName is not specified, this parameter will be ignored.

appRepStateOrProvinceName

conditional

string

128 chars

The applicant representative’s state or province.

If appRepOrganizationName is not specified, this parameter will be ignored.

appRepPostalCode

conditional

string

40 chars

The applicant representative’s postal code.

If appRepOrganizationName is not specified, this parameter will be ignored.

appRepCountryName

conditional

string

2 chars

The applicant representative’s country code.

This parameter must be an ISO 3166 two-character country code.

If appRepOrganizationName is not specified, this parameter will be ignored.

showCertificateState

optional

char

1 char

Specifies whether to show the certificate state.

The allowed values are:

  • Y — The state of the certificate generated by the order is a part of the result set.

  • N — The state of the certificate generated by the order isn’t included in the part of the result set.

ignoreLateOrgDetailsChanges

optional

char

1 char

Specifies whether to ignore the late organizational details changes.

The allowed values are:

  • Y — Sectigo will ignore newly provided values for the organizationName parameter, the various address-related parameters (for example, localityName, countryName), and the corresponding Subject fields. The organization name and address from the previous certificate will be used instead.

  • N — Sectigo will use newly provided values for the organizationName parameter, the various address-related parameters (for example, localityName, countryName), and the corresponding Subject fields, as referenced in other parts of this table.

If omitted, the value defaults to N.

updateOrgDetails

optional

char

1 char

Specifies whether to update the organizationName parameter and other address-related parameters.

The allowed values are:

  • Y — Sectigo will update the organizationName parameter, the various address-related parameters (for example, localityName, countryName), and the corresponding Subject fields.

  • N — Sectigo will use newly provided values for the organizationName parameter, the various address-related parameters (for example, localityName, countryName), and the corresponding Subject fields to create a new address.

If omitted, the value defaults to N.

showValidityPeriod

optional

char

1 char

Specifies whether to show the validity period of the certificate.

The possible values are:

  • Y — Show the validity period.

  • N — Do not show the validity period.

If omitted, the value defaults to N.

showReplOrderNumber

optional

char

1 char

Specifies whether to show the replaced order number.

The allowed values are:

  • Y — Show the replaced order number.

  • N — Do not show the replaced order number.

If omitted, the value defaults to N.

logoHostedByCA

optional

string

1 char

Indicates whether the logo and certificates are hosted on the CA or not.

The allowed options are:

  • Y — The customer would like Sectigo to host the logo and certificate file.

  • N — The customer would like to host the logo and certificate file themselves.

If omitted, the value defaults to Y.

Sample request

curl --location 'https://secure.trust-provider.com/products/!AutoReplaceMC' \
--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 'isCustomerValidated=N' \
--data-urlencode 'domainNames=domain_names' \
--data-urlencode '[email protected]' \
--data-urlencode '[email protected]' \
--data-urlencode 'csr=-----BEGIN CERTIFICATE REQUEST-----
MIIbWQYJKoZIhvcNAQcCoIIbSjCCG0YCAQExDTALBglghkgBZQMEAgEwDwYJKoZI
hvcNAQcBoAIEAKCCGHEwggzyMIILWqADAgECAhBLVWcU36fkE8Hi/55APse9MA0G
...
Hi4ZaP9ok+JrTdy01WOmCnuAIaOUdM+w3wb+DSNLh9MoqqeM2mBZdC7EGthYeg+O
RhZWrKZng/nCi4Pt0PQrKEFNaMdscl+0rnrQA+U6llop7fmztjhKtOwDR6bQ
-----END CERTIFICATE REQUEST-----' \
--data-urlencode 'markLogo=mark_logo` \
--data-urlencode 'UpdateOrgDetails=Y'

Response

The request is successful when the server returns a response with the status code = 0.

Any status code less than 0 indicates an error condition.

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

The MIME type will be text/plain for responseFormat=0 (by default).

The first line of the response represents a status code.

If the status code is less than 0, the second line contains an error message describing the error.

If the status code equals 0, the response can contain the following lines which provide:

  • The certificate state if showCertificateState=Y. The certificate state is the status of the certificate generated by this replacement.

  • The amount debited if showTotalCost=Y. The possible value is 99999990.00.

  • The product term start timestamp and product term end timestamp with a space between the dates. The product term timestamps are returned if showValidityPeriod=Y. It is expressed as a UNIX time value.

1052870400 1084406400

  • The replacement order number — The order number generated by this replacement. The replacement order number is returned if showReplacedOrderNumber=Y.

The MIME type will be application/x-www-form-urlencoded for responseFormat=1.

Response parameters

The response can contain the following parameters:

Parameter Possible Value

errorCode

A numeric code that identifies the type of error.

Always present in the response.

For more information, see Error codes.

errorMessage

A description of the error.

This parameter is absent when errorCode=0.

certificateStatus

The status of the SSL certificate generated by this replacement.

This parameter is only present when showCertificateState=Y and errorCode=0.

productTermStartDate

The timestamp when the product term has started.

It is expressed as a UNIX time value.

This parameter is only present when showValidityPeriod=Y.

productTermEndDate

The timestamp when the product term will end.

It is expressed as a UNIX time value.

This parameter is only present when showValidityPeriod=Y.

productTermDuration

The product duration in days.

This parameter is only present when showValidityPeriod=Y.

replOrderNumber

The order number generated by this replacement.

This parameter is only present when showReplOrderNumber=Y and errorCode=0.

Sample success response

errorCode=0

Sample error response

-160%0AFailed%20to%20replace%20order%20%231234567890.

Error codes

The following table outlines error responses returned by the AutoReplaceMC API endpoint. Each error response consists of an errorCode and an errorMessage indicating why the request failed.

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 recognised.

-3

The 'xxxx' 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.

-7

'xx' is not a valid ISO-3166 country!

The specified country code is not valid according to the ISO-3166 standard.

-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.

-36

The certificate has already expired!

The requested certificate has expired and cannot be processed.

-90

Permission denied for using “voucher” with 'xxxx'

The user does not have permission to use a voucher with the specified context.

-91

Permission denied! 'xxxx'

The user doesn’t have the permission to perform the specified action.

-110

CSR decoding Internal Error

An internal error occurred while decoding the CSR.

-115

No price found for 'xxxx'

No price information available for the specified item.

-160

Failed to replace order #xxxx.

The order replacement failed due to a general error.

-161

Parameter 'xxxx' is not applicable to this type of product!

The specified parameter is not valid for this product type.

-162

The CSR must not contain domain names that are not in the "domainNames" parameter!

The CSR contains domain names not listed in the domainNames parameter.

-163

The CSR must not contain domain names that are not in the list of certificate domain names!

The CSR contains domain names not listed in the certificate’s domain names.