provisionAccount — Provisioning new accounts

The provisionAccount method provisions new accounts. Account creation isn’t idempotent—​each attempted account creation provisions a new account.

The API endpoint is:

https://api.sitelock.com/v1/partner

Request format

  • SiteLockOnlineRequest: This element is used to delineate the full API request.

    • authentication: The partner’s username, password, and branding

      • username: The partner’s API username

      • password: The partner’s API password

      • partner: (Optional) The brand name to use in messaging

    • provisionAccount: The method name

      • accountInformation: This element is used to delineate the new user’s account information (for example, billing). The accountInformation element can also be used as an indication that the following payload should be added to an existing account that has previously been provisioned.

        • name: The user’s full name

        • address1: The first line of the user’s address

        • address2: The second line of the user’s address

        • city: The user’s city

        • state: The user’s state or province

        • zip: The user’s postal code

        • country: The user’s country (see the getCountriesList method and Best practices for representing state and country data for the country codes).

        • email: The user’s email address. It must be unique across all SiteLock accounts if the login element isn’t specified, since the email address will be used as the account login ID.

        • login: (Optional) The user’s unique login ID. The login must be at least 8 characters and only consist of alphanumeric characters and/or any of these five special characters: -, _, @, ., +. The value of email will be used as login when this field isn’t specified.

        • phone: The user’s phone number

        • password: The user’s account password. If a password is set during account provisioning, the user will be prompted to set a new password on first login to the SiteLock Dashboard.

        • account_id: The user’s previously provisioned account_id

          The account_id element is only used when adding to an existing account.

        • initialSubscription: The subscription ID for the account, which may be set before the account has been associated with a domain.

        • language: Two-character language code. The default language displayed on the dashboard when the user logs in.

        • isTest: A Boolean value determining if it’s a test account for the partner, and shouldn’t be billed for. Set to yes if the account is a test account.

        • reseller_account_id: (Optional) The account_id generated by the partner in their provisioning system. This value can be passed in here to maintain a link between a SiteLock account and a partner account. This value can be used later to query for subscription status using the getStatus method.

          The value of reseller_account_id must be unique for each partner.

      • siteInformation: This element is used to delineate the new user’s domain.

        • subscription: The ID of the SiteLock Plan that was sold. Use this element when the value of the type attribute in the getPlanList response is plan.

        • bundle: The ID of the SiteLock Bundle that was sold. Use this element when the value of the type attribute in the getPlanList response is bundle.

          When a partner is provisioning SiteLock bundles, the bundle element must be specified, and the subscription element must not.

        • addon: (Optional and repeatable) The ID of the SiteLock Add-on that was sold. Use this element when the value of the type attribute in the getPlanList response is addon (for example, Firewall & CDN or PCI).

          You may need to include additional elements in the siteInformation section depending on the provisioned add-on. For more information, see the request format for provisioning Firewall & CDN, Backup & Recovery, DNS, or PCI compliance.

        • amount: [optional attribute] - The amount the user was billed for this add-on.

          This element isn’t optional when partner invoicing is based on revenue sharing.

        • renewal_date: (Optional) The renewal date for the subscription (including any add-ons) being provisioned. If different subscription renewal dates are required for the primary subscription and add-on subscriptions, provision add-ons separately using provisionAddon as detailed in Provisioning add-on products. The date format should be expressed in the YYYY-MM-DD format (for example, 2021-01-01).

        • domain: The domain that will be serviced by SiteLock. See also Provisioning parked sites.

        • domainEmail: An email address at the domain that will be serviced by SiteLock. See also Provisioning parked sites.

        • trustedDomain: A Boolean indicating if this domain has a trusted origin. See also Trusted domains and Provisioning parked sites.

        • amount: The decimal amount the user was billed for this site. This field applies to items added with the subscription and bundle elements, but not to items added with the addon element. See the amount attribute of the addon element for more information.

          This element isn’t optional when partner invoicing is based on revenue sharing.

        • waf_skip_network_certificate: (optional, default value is "0") Use this parameter to skip the network certificate (CA validation process) for your deployment. If you choose to skip the CA validation, you will need to provide your own certificate for this deployment via the uploadWafCertificate method.

          Use this element when provisioning an addon via provisionAccount. It should only be included in the request if the <addon> element is also being sent.

Example request

<SiteLockOnlineRequest>
    <authentication>
        <user>Username</user>
        <password>Password</password>
        <partner>Our Brand</partner>
    </authentication>
    <provisionAccount>
        <accountInformation>
            <name>John Smith</name>
            <address1>100 Main St</address1>
            <address2>Second Address Line</address2>
            <city>Boston</city>
            <state>MA</state>
            <zip>12345</zip>
            <country>US</country>
            <email>[email protected]</email>
            <phone>555-123-4567</phone>
            <password>secret</password>
            <initialSubscription>8</initialSubscription>
            <language>EN</language>
            <isTest>No</isTest>
            <reseller_account_id>123</reseller_account_id>
        </accountInformation>
        <siteInformation>
            <subscription>8</subscription>
            <addon>123</addon>
            <addon amount="25.00">124</addon>
            <renewal_date>2015-01-01</renewal_date>
            <domain>johnsmith.com</domain>
            <domainEmail>[email protected]</domainEmail>
            <trustedDomain>yes</trustedDomain>
            <amount>5.00</amount>
            <waf_skip_network_certificate>1</waf_skip_network_certificate>
        </siteInformation>
    </provisionAccount>
</SiteLockOnlineRequest>

Response format

Example success response

<SiteLockOnlineResponse>
    <provisionAccount>
        <accountInformation>
            <id>12345</id>
        </accountInformation>
        <siteInformation>
            <site>
                <addon>
                    <status>ok</status>
                    <subscription>123</subscription>
                    <subscription_id>987654</subscription_id>
                    <type>SERVICES</type>
                </addon>
                <site_id>12345</site_id>
                <domain>domain.com</domain>
            </site>
        </siteInformation>
    </provisionAccount>
</SiteLockOnlineResponse>

The successful response returns the account_id and site_id that should be stored for use in future update or deletion requests. These IDs will ensure that you’re always referencing the intended account. In addition, if add-ons are provisioned, each successful add-on will return a subscription_id element, containing a unique ID that can be used later to manage this subscription (for example, to remove it). These values should also be stored.

Example error response

<SiteLockOnlineResponse>
    <provisionAccount>
        <error>Could not parse XML request</error>
    </provisionAccount>
</SiteLockOnlineResponse>

The 500 Error status returns an XML payload containing an error message. This error message helps to identify where the issue with the account provisioning lies. The most common error is invalid XML, such as unescaped characters or elements that aren’t closed. Other errors would include the attempt to provision a duplicate account, or other account information issues.

Example error responses—​TrueShield Add-on

Current format

<SiteLockOnlineResponse>
    <provisionAccount>
        <accountInformation>
            <id>100000561</id>
        </accountInformation>
        <error>
            <code>AEX</code>
            <content>ANP Provision Error [3003]: Site Requires SSL</content>
        </error>
        <siteInformation>
            <site>
                <addon>
                    <error_code>AEX</error_code>
                    <error_message>Site Requires SSL</error_message>
                    <extended_error_code>3003</extended_error_code>
                    <status>error</status>
                    <subscription>9999</subscription>
                    <type>ANP</type>
                    <will_retry>0</will_retry>
                </addon>
                <domain>example.com</domain>
                <site_id>100005052</site_id>
            </site>
        </siteInformation>
    </provisionAccount>
</SiteLockOnlineResponse>

Legacy format

<SiteLockOnlineResponse>
    <provisionAccount>
        <accountInformation>
            <id>100000562</id>
        </accountInformation>
        <siteInformation>
            <site>
                <addon>
                    <code>3003</code>
                    <error_code>AEX</error_code>
                    <extended_error_code>3003</extended_error_code>
                    <message>Site Requires SSL</message>
                    <error_message>Site Requires SSL</error_message>
                    <status>error</status>
                    <type>ANP</type>
                    <will_retry>0</will_retry>
                </addon>
                <domain>example.com</domain>
                <site_id>100005053</site_id>
            </site>
        </siteInformation>
    </provisionAccount>
</SiteLockOnlineResponse>

Newer partners are likely to see the first response type, while others are more likely to see the latter. They are primarily distinguished by the presence (or absence) of an error element belonging to the provisionAccount element, as a sibling to accountInformation and siteInformation.

In either case, the addon element has the following elements:

  • error_code: An error code from either:

  • extended_error_code: Either a value from Firewall & CDN extended error codes or -1, indicating the major error_code prevented Firewall & CDN from even attempting provisioning due to errors which couldn’t be resolved (for example, missing site information).

  • error_message: The error message that explains the issue in question.

  • will_retry: A 0 or 1 indicating, as false and true, respectively, whether the error encountered (as detailed in extended_error_code) is able to be retried. If so (for example, the site doesn’t resolve), then it will be retried for 12 days before the subscription will be automatically cancelled. During this time, it’s considered active. See getAnpProvisioningStatus for more information on managing this process.

  • code: Legacy mode only. If error_code is AEX, this field will contain the contents of extended_error_code. Otherwise it will contain error_code, for example, values from Additional error codes for Firewall & CDN.

Trusted domains

A domain that has been newly registered with the partner (and not with a third-party domain registrar) is considered a trusted domain. These domains go through a less rigorous validation process, since it’s expected that the domains have gone through some initial validation.

As a precaution, if many domains from a partner are found to be of low standard, SiteLock may ignore the supplied value of the trustedDomain element.

When the trusted_domain flag isn’t sent in at the time of provisioning, we check the partner preference specified in the partner customization phase. If verify_before_scan = "yes" (default value), then domain ownership verification is enforced before the application scan is run.

Provisioning parked sites

See also: Using modifyAccount with a parked site.

This is used when a partner sells a SiteLock product, but the user hasn’t selected a domain to which to apply the services.

The partner can call provisionAccount without specifying the domain, trusted_domain, and domain_email elements. This causes SiteLock to create a parked site with credit set aside for the services provisioned on this site. SiteLock returns a site_id for this parked site. A valid domain name is required for Scan and Firewall & CDN services to begin functioning. Later, when the domain name is known, the partner can call modifyAccount to convert the site into a regular site with services.

All the regular checks that are part of provisioning are performed at this time. Examples are:

  • siteInformation may not contain both subscription and bundle.

  • When a bundle is specified and a separate addon is also specified, which refers to a product already contained in the bundle, the provisioning attempt results in an error.

Example request

<SiteLockOnlineRequest>
    <authentication>
        <user>Username</user>
        <password>Password</password>
    </authentication>
    <provisionAccount>
        <accountInformation>
            <account_id>100000587</account_id>
        </accountInformation>
        <siteInformation>
            <subscription>47</subscription>
        </siteInformation>
    </provisionAccount>
</SiteLockOnlineRequest>

Example success response

<SiteLockOnlineResponse>
    <provisionAccount>
        <accountInformation>
            <id>100000587</id>
        </accountInformation>
        <siteInformation>
            <site>
                <domain></domain>
                <site_id>100005104</site_id>
            </site>
        </siteInformation>
    </provisionAccount>
</SiteLockOnlineResponse>

Restricted operations on parked sites

The only calls that are allowed on a parked site are:

The following operations on parked sites will result in the errors shown in the examples:

Example error response—​Provisioning/modifying an add-on on a parked domain
<SiteLockOnlineResponse>
    <provisionAddon>
        <addonStatuses>
            <addonStatus>
                <account_id>100000587</account_id>
                <code>COP</code>
                <message>Site is parked, pending domain, and cannot accept new subscriptions until activated</message>
                <site_id>100005109</site_id>
                <status>error</status>
                <subscription>4586</subscription>
            </addonStatus>
        </addonStatuses>
    </provisionAddon>
</SiteLockOnlineResponse>
Example error response—​Deleting an add-on on a parked domain
<SiteLockOnlineResponse>
    <deleteAddon>
        <addonStatuses>
            <addonStatus>
                <account_id>100000587</account_id>
                <code>COP</code>
                <message>Site is parked, pending domain, and cannot delete subscriptions until activated</message>
                <site_id>100005109</site_id>
                <status>error</status>
                <subscription>4586</subscription>
            </addonStatus>
        </addonStatuses>
    </deleteAddon>
</SiteLockOnlineResponse>
Example error response—​modifyAccount on a parked site
<SiteLockOnlineResponse>
    <error>Site is parked, pending domain, and cannot accept new subscriptions until activated</error>
</SiteLockOnlineResponse>