Request

Endpoint: !GetMasterAccountDetails

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

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

64 chars

Your account password.

This value is case sensitive.

orderNumber

required

string

128 chars

Specifies the order number with the Enterprise Authentication record.

createNotBefore

optional

string

128 chars

The timestamp indicates when the Enterprise Authentication record was created. It is expressed as a UNIX time value.

The Enterprise Authentication created before this time will be ignored.

The date range requested using createNotBefore and createNotAfter should not exceed three years.

If both createNotBefore and createNotAfter are omitted, the period defaults to the three years preceding the current date.

createNotAfter

optional

integer

The timestamp indicates when the Enterprise Authentication record was created. It is expressed as a UNIX time value.

The Enterprise Authentication created after the time will be ignored.

The date range requested using createNotBefore and createNotAfter should not exceed three years.

If createNotAfter is omitted, its value defaults to the current date.

If createNotAfter is specified, createNotBefore should not be omitted.

If both createNotBefore and createNotAfter are omitted, the period defaults to the three years preceding the current date.

expireNotBefore

optional

integer

The timestamp indicates when the Enterprise Authentication expires. It is expressed as a UNIX time value.

The Enterprise Authentication that expires before this time will be ignored.

Date range requested using expireNotBefore and expireNotAfter should not exceed three years.

If both expireNotBefore and expireNotAfter are omitted, the period defaults to the three years preceding the current date.

expireNotAfter

optional

integer

The timestamp indicates when the Enterprise Authentication expires. It is expressed as a UNIX time value.

The Enterprise Authentication that expires after this time will be ignored.

The date range requested using expireNotBefore and expireNotAfter should not exceed three years.

If expireNotAfter is omitted, the value defaults to the current date.

If expireNotAfter is specified, expireNotBefore should not be omitted.

If both expireNotBefore and expireNotAfter are omitted, the period defaults to the three years preceding the current date.

status

optional

integer

The status of the Enterprise Authentication.

The allowed values are:

  • 1 — Awaiting confirmation.

  • 2 — Active.

  • 3 — Rejected.

  • 11 — Reset.

  • 12 — Expired.

  • 21 — Awaiting validation.

organizationName

optional

string

64 chars

The organization name.

streetAddress1

optional

string

128 chars

The organization street address.

streetAddress2

optional

string

128 chars

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

streetAddress3

optional

string

128 chars

The third part of the organization’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

40 chars

The organization’s postal code.

countryName

optional

string

2 chars

The ISO 3166 two-character code for the organization’s country.

Forename

optional

string

64 chars

The admin’s first name.

Surname

optional

string

64 chars

The admin’s surname.

emailAddress

optional

string

255 chars

The admin’s email address.

telephoneNumber

optional

string

32 chars

The admin’s telephone number.

organizationIdentifier

optional

char

100 chars

(S/MIME Organization Pre-Validations only) The organization identifier.

responseFormat

optional

integer

Specifies the response format.

The allowed values are:

  • 1 — Newline-delimited parameters.

  • 2 — JSON.

If omitted, the value defaults to 1.

prevalidationOrderNumber

optional

char

128 char

(OV/EV SSL and OV S/MIME certificates only) The pre-validation ID.

This parameter should be provided to use Organization Pre-Validation for instant issuance.

Sample request

The following example shows a sample request to getMasterAccountDetails with all required parameters.

curl --location 'https://secure.trust-provider.com/products/!GetMasterAccountDetails' \
--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 'responseFormat=2'

Response

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

Any status code less than 0 indicates an error condition.

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

Response parameters

Response with responseFormat=1

The MIME type will be application/x-www-form-urlencoded for responseFormat=1, because the format of the response will be the same URL-encoded format as the request (for example, name1=value1&name2=value2).

The following table displays the various parameters that can appear in the response.

Parameter Type Description

errorCode

integer

The error code.

For more information, see Error codes.

errorMessage

string

The explanation of the error.

X_orderNumber

string

The order number.

X_statusCode

integer

The status code of the enterprise authentication.

X_statusDesc

string

The status description of the enterprise authentication.

X_creationDate

integer

The time the enterprise authentication was confirmed (created before confirmation).

It is expressed as a UNIX time value.

X_expiryDate

integer

The time until the enterprise authentication expires.

It is expressed as a UNIX time value.

X_emailAddress

string

The Enterprise Authentication email address.

X_forename

string

The admin’s first name.

X_surname

string

The admin’s surname.

X_telephoneNumber

string

The admin’s telephone number.

X_organizationName

string

The name of the company.

X_organizationalUnitName

string

The department within the company.

X_postOfficeBox

string

The organization post office box.

X_streetAddress1

string

The street address where the organization is incorporated.

X_streetAddress2

string

The second part of the street address where the organization is incorporated (if necessary).

X_streetAddress3

string

The third part of the street address where the organization is incorporated (if necessary).

X_localityName

string

The city in which the organization is incorporated.

X_stateOrProvinceName

string

The state or province in which the organization operates.

X_postalCode

string

The postal code at which the organization operates.

X_countryName

string

The country in which the organization operates.

The country name should be a two-character ISO 3166 country code.

X_joiLocalityName

string

The city or town (if any) in which the company is incorporated.

Available for EV certificates.

X_joiStateOrProvinceName

string

The State or Province (if any) in which the company is incorporated.

Available for EV certificates.

X_joiCountryName

string

The country in which the company is incorporated.

X_joiCountryName should be a two-character ISO 3166 country code.

Available for EV certificates.

X_assumedName

string

The d/b/a (does business as) name (if any) for the company.

Available Only for EV certificates.

X_dateOfIncorporation

string

The date of incorporation (YYYY-MM-DD) of the company.

Applicable only for EV certificates.

This is useful information for Validation purposes.

X_dunsNumber

string

DUNS number — a unique nine-digit identifier for businesses, provided by the company Dun & Bradstreet.

X_companyNumber

string

The company registration number.

X_businessCategory

string

The legal classification of the organization.

X_type

string

The certificate type(s) the Organization Pre-Validation is appropriate for.

X_organizationIdentifier

string

(S/MIME Organization Pre-Validations only) The organization identifier.

Response with responseFormat=2

The MIME type will be application/json for responseFormat=2.

The possible values for a JSON object are the same as for URL-encoded response.

Sample success response

{
    "data": {
        "noOfResults": 1,
        "orders": [
            {
                "orderNumber": "xxxxxx",
                "type": "EV",
                "statusCode": 21,
                "statusDesc": "Awaiting Validation",
                "creationDate": 1733488716,
                "expiryDate": null,
                "emailAddress": "[email protected]",
                "telephoneNumber": null,
                "surName": "signerSurname",
                "foreName": "signerForename",
                "organizationName": "Company Name XXXX",
                "organizationalUnitName": null,
                "postOfficeBox": null,
                "streetAddress1": "streetAddress1",
                "streetAddress2": null,
                "streetAddress3": null,
                "localityName": null,
                "stateOrProvinceName": "California",
                "postalCode": null,
                "countryName": "US",
                "joiLocalityName": null,
                "joiStateOrProvinceName": "California",
                "joiCountryName": "US",
                "assumedName": null,
                "dateOfIncorporation": null,
                "dunsNumber": null,
                "companyNumber": null,
                "businessCategory": null,
                "organizationIdentifier": null
            }
        ]
    },
    "error": {
        "code": 0,
        "description": null,
        "item": null
    }
}

Sample error response

errorCode=-16&errorMessage=Incorrect+login+details%2C+account+is+locked%2C+password+has+expired+or+your+source+IP+is+blocked.

Error codes

The following table outlines error responses returned by the getMasterAccountDetails 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

‘xxxx’ is an unrecognized argument!

The provided argument is not recognized.

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

-42

Call limit reached! Please try again later

The maximum number of API calls has been reached.