Get users

GET /users

List all users in the API consumer’s brand.

By default, only 20 users will be returned in the response, always starting with the first user created. You can change this behaviour by using the limit and offset parameters.

Typically, deleted users are not included in the response. If you want to include these users then set the showDeleted parameter.

Parameters

limit integer Number of users that will be returned in the response. Default: 20.
offset integer Offset to the first user to be returned in the response. Default: 0.
showDeleted integer Exclude users in the response that have been soft deleted. By default all users will be included whether they are deleted or not.
dateFrom string Filter the response to users that have been created from and including this date. By default, all users will be incuded.
dateTo string Filter the response to users that have been created up to and including this date. By default, all users will be incuded.
resellerRef integer Version 44 and above only. Return only users belonging to a particular reseller. The reseller must belong to your brand.

Response

{
    "count":"1",
    "accountHolders":
    [
        {
            "ref": 1,
            "firstName": "Foo",
            "lastName": "Bar",
            "username": "foobar",
            "email": "foobar@example.com",
            "created":
            {
                "date": "2012-06-28 11:37:12",
                "timezone_type": 3,
                "timezone": "Europe\/London"
            },
            "lastLogin":
            {
                "date": "2012-12-17 15:17:59",
                "timezone_type": 3,
                "timezone": "Europe\/London"
            },
            "deleted": false,
            "accountStatus": "allowed",
            "newsletter": 0,
            "suspended": 0,
            "languageCode": "en",
            "phoneNumber": "gvfdsgfdfs",
            "cpfNumber": "",
            "address1": "dsfrds",
            "address2": "fdsfds",
            "city": "fdsfds",
            "state": "FDSFSD",
            "company": "",
            "country": "Afghanistan",
            "postcode": "dsfsf",
            "accountPackages":
            [
                {
                    "ref": 1,
                    "deleteOnExpiry": 0,
                    "startDateTime":
                    {
                        "date": "2012-06-28 11:37:12",
                        "timezone_type": 3,
                        "timezone": "Europe\/London"
                    },
                    "package":
                    {
                        "ref": 16,
                        "name": "Demo Account"
                    },
                    "billingCycle":
                    {
                        "billingPeriodMonths": 1,
                        "expiryDate":
                        {
                            "date": "2013-06-06 00:00:00",
                            "timezone_type": 3,
                            "timezone": "Europe\/London"
                        }
                    }
                }
            ]
        }
    ]
}

Exceptions

invalidResellerRef You are trying to filter by a reseller that does not belong to your brand.

Get user

GET /users/:userRef

Response

{
    "accountHolder":
    {
        "ref": 1,
        "firstName": "Test",
        "lastName": "User",
        "username": "testuser",
        "email": "testuser@example.com",
        "suspended": 0,
        "beta": false,
        "languageCode": "en",
        "phoneNumber": null,
        "address1": "",
        "address2": "",
        "city": "",
        "postcode": "",
        "country": "",
        "newsletter": 0,
        "currencyRef": 1,
        "state": "",
        "capabilities":
        {
            "liveSites": "5",
            "allowUsers": "1",
            "cdnEnabled": "N",
            "cssEditing": "1",
            "themeLevel": "1",
            "freeDomains": "0",
            "htmlEditing": "0",
            "pagesLimited": "100",
            "storageLimit": "10485760",
            "templateTier": "2",
            "domainMapping": "0",
            "googleAnalytics": "1",
            "ecommerceAllowed": "1",
            "googleAdWordVoucher": "0",
            "allowExternalRedirects": "0",
            "allowTemplateSave": "0",
            "mailboxes": "0",
            "mobile": "0",
            "siteLock": "0",
            "mobileSites": "0",
            "mobilePublishing": 0,
            "restrictPagesOnPublish": "0"
        },
        "accountPaymentMethodRef": null,
        "cpfNumber": null,
        "cpfCompany": 0,
        "company": "",
        "deleted": false,
        "storageBytesUsed": "0",
        "created":
        {
            "date": "2012-12-17 15:41:42",
            "timezone_type": 3,
            "timezone": "Europe\/London"
        },
        "lastLogin": null,
        "accountStatus": "allowed",
        "subscriptionPackageRef": 16,
        "brandRef": 1,
        "nrtStatus": false,
        "nrtDaysToExpiry": 0,
        "editorAccess": true,
        "usedFreeDomains": 0
    }
}

Create user

POST /users

Create a new user in the specified brand.

Note that the brandRef must match that of the caller’s designated brand.

Typically, after you have created a user, a site is created for the user via Create Site.

Input

brandRef integer Required. Brand of the account holder.
firstName string Required. 1-150 characters.
lastName string Required. 1-150 characters.
username string Required. Username to be used to login the user to their account and sites. 1-255 characters.
password string Required. 7-100 characters. Prior to version 37 the maximum length was 19 characters.
email string Required. E-mail address of the user. E-mails sent from the system in response to user lifecycle events (for example, subscription payment, renewal payments, cancellation, etc.) are sent to this address. 5-254 characters, of which the local part (example in example@domain.com) must be no more than 64 characters.
languageCode string Required. User’s language code. See List Brand Languages to determine the languages that are available.
resellerRef integer Optional. The reseller to which the user belongs.
metadata array Optional. Name and value pairs of user Metadata. Name 2-127 characters. Value 2-255 characters. Available from version 7.106.
{
    "firstName": "Test",
    "lastName": "User",
    "username": "testuser",
    "password": "password",
    "email": "testuser@example.com",
    "brandRef": 1,
    "resellerRef": 3,
    "languageCode": "en",
    "metadata": {"Name1": "Value1", "Name2": "Value2"}
}

Response

Status: 201 Created
{
    "accountHolder":
    {
        "ref": 1,
        "firstName": "Test",
        "lastName": "User",
        "username": "testuser",
        "email": "testuser@example.com",
        "suspended": 0,
        "beta": false,
        "languageCode": "en",
        "phoneNumber": null,
        "address1": "",
        "address2": "",
        "city": "",
        "postcode": "",
        "country": "",
        "newsletter": 0,
        "currencyRef": 1,
        "state": "",
        "capabilities":
        {
            "liveSites": "5",
            "allowUsers": "1",
            "cdnEnabled": "N",
            "cssEditing": "1",
            "themeLevel": "1",
            "freeDomains": "0",
            "htmlEditing": "0",
            "pagesLimited": "100",
            "storageLimit": "10485760",
            "templateTier": "2",
            "domainMapping": "0",
            "googleAnalytics": "1",
            "ecommerceAllowed": "1",
            "googleAdWordVoucher": "0",
            "allowExternalRedirects": "0",
            "allowTemplateSave": "0",
            "mailboxes": "0",
            "mobile": "0",
            "siteLock": "0",
            "mobileSites": "0",
            "mobilePublishing": 0,
            "restrictPagesOnPublish": "0"
        },
        "accountPaymentMethodRef": null,
        "cpfNumber": null,
        "cpfCompany": 0,
        "company": "",
        "deleted": false,
        "storageBytesUsed": 0,
        "created": {
            "date": "2015-10-22 17:01:44",
            "timezone_type": 3,
            "timezone": "Europe/London"
        },
        "lastLogin": null,
        "accountStatus": "allowed"
    }
}

Edit user

PUT /users/:userRef

Update data for the specified user.

This will only update the properties that have been included in the request. All properties that are missing from the request will remain the same.

Input

firstName string 1-150 characters.
lastName string 1-150 characters.
username string Username to be used to login the user to their account and sites. 1-255 characters.
password string 7-100 characters. Prior to version 7.37 the maximum length was 19 characters.
email string E-mail address of the user. E-mails sent from the system in response to user lifecycle events (for example, subscription payment, renewal payments, cancellation, etc.) are sent to this address. 5-255 characters.
languageCode string User’s language code. See List Brand Languages to determine the languages that are available.
{
    "firstName": "Testing"
}

Response

Status: 200 OK
{
    "accountHolder":
    {
        "ref": 1,
        "firstName": "Testing",
        "lastName": "User",
        "username": "testuser",
        "email": "testuser@example.com",
        "suspended": 0,
        "beta": "0",
        "languageCode": "en",
        "phoneNumber": null,
        "address1": "",
        "address2": "",
        "city": "",
        "postcode": "",
        "country": "",
        "newsletter": 0,
        "currencyRef": 1,
        "state": "",
        "capabilities":
        {
            "liveSites": "5",
            "allowUsers": "1",
            "cdnEnabled": "N",
            "cssEditing": "1",
            "themeLevel": "1",
            "freeDomains": "0",
            "htmlEditing": "0",
            "pagesLimited": "100",
            "storageLimit": "10485760",
            "templateTier": "2",
            "domainMapping": "0",
            "googleAnalytics": "1",
            "ecommerceAllowed": "1",
            "googleAdWordVoucher": "0",
            "allowExternalRedirects": "0",
            "allowTemplateSave": "0",
            "mailboxes": "0",
            "mobile": "0",
            "siteLock": "0",
            "mobileSites": "0",
            "mobilePublishing": 0,
            "restrictPagesOnPublish": "0"
        },
        "accountPaymentMethodRef": null,
        "cpfNumber": null,
        "cpfCompany": 0,
        "company": "",
        "deleted": false,
        "storageBytesUsed": "0",
        "created":
        {
            "date": "2012-12-17 15:41:42",
            "timezone_type": 3,
            "timezone": "Europe\/London"
        },
        "lastLogin": null,
        "accountStatus": "allowed"
    }
}

Delete user

DELETE /users/:userRef

Delete the specified user.

The user is not deleted from the database, but it is marked for deletion and will not be included in further API calls unless deleted users are explicitly requested.

See our handy guide on deleting users.

Response

Status: 204 No Content

Anonymise user

POST /users/:userRef/anonymise

Note: Available from BaseKit version 7.67.

Anonymises the specified user, setting all personal details to “anonymised”. See our handy guide on deleting users.

Response

Status: 204 No Content

Create auto-login hash

POST /users/:userRef/auto-login

Automatically login an account holder to one of the sites that they own.

This method will return a secret hash string that can be used to provide a login URL to the user. The login URL will automatically log the user in to their website in the editor. If the site does not have a template yet then the user will arrive in the template picker.

If the site for login has URL www.example.com and the hash returned from this call is 0123456789abcdef then the login URL should be constructed as follows:

www.example.com?hash=0123456789abcdef

The hash string returned may only be used to login the user once. You must call this API method to generate a new hash code every time the user needs to login.

The hash string is only valid for 1 hour after the time that it is created.

Choosing a Template (v41 onwards)

After sign-up of a new account holder, and creation of their site, you may want to direct them to the template picker initially rather than the site editor.

To do this redirect to the following login URL:

http://flow.partner.com/login?hash=0123456789abcdef&r=http://templatesv7.partner.com/?siteRef=1

Where partner.com is your url for the BaseKit platform, hash is replaced by the value returned by this call and the siteRef number is the ref returned when you created the account holder’s site.

You can choose what template categories or types are selected by default by appending the parameter %26selectedCategory=travel or %26selectedType=blog to the above URL.

So to login an account holder, direct them straight to the template picker and show the category travel you would redirect to the following URL:

http://flow.partner.com/login?hash=0123456789abcdef&r=http://templatesv7.partner.com/?siteRef=1%26selectedCategory=travel

You can retrieve a full list of template categories using List Template Categories, the parameter to pass in the above URL is the category key.

Input

siteRef integer Site to log in to

Response

Status: 200 OK
{
    "hash": "0123456789abcdef"
}

Get user’s packages

GET /users/:userRef/account-packages

A user may only have one subscription package. It is possible for a user to have multiple packages of other types, but most brands do not support this functionality.

Response

{
    "accountPackages":
    [
        {
            "ref":207,
            "startDateTime":
            {
                "date":"2012-12-17 15:41:42",
                "timezone_type":3,
                "timezone":"Europe\/London"
            },
            "endDateTime":null,
            "updated":
            {
                "date":"2012-12-17 15:41:42",
                "timezone_type":3,
                "timezone":"Europe\/London"
            }
            ,
            "deleteOnExpiry":0,
            "billingPeriodMonths":1,
            "package":
            {
                "ref":16,
                "name":"Demo Account",
                "active":1,
                "global":0,
                "urlID":"demo",
                "notifyMarketing":"N",
                "productType":"subscription",
                "type":"demo",
                "contentType":"bundle",
                "offerRebillMonths":0,
                "trialDays":0,
                "imageURL":"",
                "requirePurchasedDomain":false,
                "brandRef":1,
                "brandName":"BaseKit",
                "defaultCurrencyRef":1,
                "currencyCode":"GBP",
                "currencyName":"Pound Sterling",
                "currencyTitle":"GBP Pound Sterling",
                "capabilities":
                {
                    "liveSites":"5",
                    "allowUsers":"1",
                    "cdnEnabled":"N",
                    "cssEditing":"1",
                    "themeLevel":"1",
                    "freeDomains":"0",
                    "htmlEditing":"0",
                    "pagesLimited":"100",
                    "storageLimit":"10485760",
                    "templateTier":"2",
                    "domainMapping":"0",
                    "googleAnalytics":"1",
                    "ecommerceAllowed":"1",
                    "googleAdWordVoucher":"0",
                    "allowExternalRedirects":"0",
                    "allowTemplateSave":"0",
                    "mailboxes":"0",
                    "mobile":"0",
                    "siteLock":"0",
                    "mobileSites":"0",
                    "mobilePublishing":0,
                    "restrictPagesOnPublish":"0"
                }
            }
        }
    ]
}

Add user package

POST /users/:userRef/account-packages

Associate a package to the specified user. The user will inherit all the features and capabilities that are available in the package.

This method is used for Subscription, Upgrade, Downgrade and Cancellation.

A user may only have one subscription package. If a new subscription package is associated with their account via this method then the existing subscription package is automatically removed.

Input

packageRef integer Required. Package to add
billingFrequency integer Value is in months. Typically this will be 1 for monthly or 12 for annual, but it can be any number. It is critical that the correct billing frequency is passed in as this is used for provisioning and billing of the user.
{
    "packageRef":18
}

Response

Status: 200 OK
{
    "capabilities":
    {
        "allowUsers":"1",
        "cdnEnabled":"0",
        "cssEditing":"1",
        "domainMapping":"1",
        "ecommerceAllowed":"0",
        "freeDomains":"0",
        "googleAdWordVoucher":"0",
        "googleAnalytics":"1",
        "htmlEditing":"1",
        "liveSites":"5",
        "pagesLimited":"9999999",
        "storageLimit":"1073741824",
        "themeLevel":"1"
    }
}

Get a single user profile

GET /users/:userRef/profiles/:profileRef

Profiles can be associated with a site. A profile contains information which can be used by a site such as email, business name etc.

See the profile field reference for a list of properties.

Response

{
    "profile": {
        "ref": 1,
        "userRef": 1,
        "fields": [
            {
                "name": "business",
                "value": "Example site"
            },
            {
                "name": "headline",
                "value": "An example headline"
            }
        ]
    }
}

Edit user profile

PUT /users/:userRef/profiles/:profileRef

This will only update the properties that have been included in the request. All properties that are missing from the request will remain the same.

See the profile field reference for a list of properties.

Input

fields array Profile fields to create or update
{
    "fields": [
        {
            "name":"foo",
            "value":"bar"
        }
    ]
}

Response

{
    "profile": {
        "profileRef": 1
    }
}

Get user's sites

GET /users/:userRef/sites

List all sites associated with the user.

Input

deleted integer Whether to include deleted sites with the result.
{
    "fields": [
        {
            "deleted":"1"
        }
    ]
}

Response

{
    "sites":
    {
        "ref": 1,
        "reverseParentRef": null,
        "domains": {
            "1": "test.basekitexample.com"
        },
        "contentMapSite": null,
        "template": 1,
        "templateWidgetVersion": 1,
        "primaryDomain": {
            "ref": 1,
            "domainName": "test.basekitexample.com"
        },
        "lastPublish": {
            "date": "2015-01-15 16:00:24",
            "timezone_type": 3,
            "timezone": "Europe\/London"
        },
        "brandRef": 1,
        "version": 84,
        "enabled": true,
        "privateWidgets": null,
        "mobileSiteRef": null,
        "mobile": false,
        "profileRef": 1,
        "redirectToPrimary": false,
        "siteType": "responsive",
        "activationStatus": null,
        "revertType": null,
        "isReversible": false,
        "responsiveSiteRef": null,
        "ready": true,
        "cookieWarning": false,
        "cookieWarningUrl": null,
        "templateSelected": true,
        "siteLockDomainRef": null,
        "primaryUrl": "test.basekitexample.com",
        "live": true,
        "previouslyPublished": 1,
        "pages": "5",
        "owned": true,
        "profile": {
            "ref": 1,
            "fields":
            {
                "name": "business",
                "value": ""
            },
            {
                "name": "headline",
                "value": ""
            },
            {
                "name": "strapline",
                "value": ""
            },
            {
                "name": "companydescription",
                "value": ""
            },
            {
                "name": "copyright",
                "value": ""
            },
            {
                "name": "email",
                "value": ""
            },
            {
                "name": "address",
                "value": ""
            },
            {
                "name": "address1",
                "value": ""
            },
            {
                "name": "address2",
                "value": ""
            },
            {
                "name": "postalcode",
                "value": ""
            },
            {
                "name": "country",
                "value": ""
            },
            {
                "name": "phone",
                "value": ""
            },
            {
                "name": "twitter",
                "value": ""
            },
            {
                "name": "linkedin",
                "value": ""
            },
            {
                "name": "facebook",
                "value": ""
            },
            {
                "name": "googleplus",
                "value": ""
            },
            {
                "name": "youtube",
                "value": ""
            },
            {
                "name": "rss",
                "value": ""
            },
            {
                "name": "logo",
                "value": ""
            },
            {
                "name": "logowidth",
                "value": ""
            },
            {
                "name": "logoheight",
                "value": ""
            },
            {
                "name": "yelpbusinessid",
                "value": ""
            },
            {
                "name": "featureimage",
                "value": "http:\/\/files.basekitexample.com\/\/screenshot2014-11-06at12.27.28.png"
            }
        },
        "isOnLatestSqlRevision": true
    },
    {
        "ref": 2,
        "reverseParentRef": null,
        "domains": {
            "2": "test2.basekitexample.com",
            "3": "test3.basekitexample.com",
        },
        "contentMapSite": null,
        "template": 1,
        "templateWidgetVersion": 1,
        "primaryDomain": {
            "ref": 2,
            "domainName": "test2.basekitexample.com"
        },
        "lastPublish": {
            "date": "2015-01-13 10:39:13",
            "timezone_type": 3,
            "timezone": "Europe\/London"
        },
        "brandRef": 1,
        "version": 84,
        "enabled": true,
        "privateWidgets": null,
        "mobileSiteRef": null,
        "mobile": false,
        "profileRef": 2,
        "redirectToPrimary": false,
        "siteType": "responsive",
        "activationStatus": null,
        "revertType": null,
        "isReversible": false,
        "responsiveSiteRef": null,
        "ready": true,
        "cookieWarning": false,
        "cookieWarningUrl": null,
        "templateSelected": true,
        "siteLockDomainRef": null,
        "primaryUrl": "test2.basekitexample.com",
        "live": false,
        "previouslyPublished": 1,
        "pages": "5",
        "owned": true,
        "profile": {
            "ref": 2,
            "fields":
            {
                "name": "business",
                "value": ""
            },
            {
                "name": "headline",
                "value": ""
            },
            {
                "name": "strapline",
                "value": ""
            },
            {
                "name": "companydescription",
                "value": ""
            },
            {
                "name": "copyright",
                "value": ""
            },
            {
                "name": "email",
                "value": ""
            },
            {
                "name": "address",
                "value": ""
            },
            {
                "name": "address1",
                "value": ""
            },
            {
                "name": "address2",
                "value": ""
            },
            {
                "name": "postalcode",
                "value": ""
            },
            {
                "name": "country",
                "value": ""
            },
            {
                "name": "phone",
                "value": ""
            },
            {
                "name": "twitter",
                "value": ""
            },
            {
                "name": "linkedin",
                "value": ""
            },
            {
                "name": "facebook",
                "value": ""
            },
            {
                "name": "googleplus",
                "value": ""
            },
            {
                "name": "youtube",
                "value": ""
            },
            {
                "name": "rss",
                "value": ""
            },
            {
                "name": "logo",
                "value": ""
            },
            {
                "name": "logowidth",
                "value": ""
            },
            {
                "name": "logoheight",
                "value": ""
            },
            {
                "name": "yelpbusinessid",
                "value": ""
            },
            {
                "name": "featureimage",
                "value": ""
            }
        },
        "isOnLatestSqlRevision": true
    }
}

Requesting a User Report

POST /user-reports

Request that a user report be queued for creation.

Response

{
    "job": "ohckansqqgtt1p4d8r5jo4jik9k76pax"
}

Fetching a User Report

GET /user-reports/:job

Response

Response will be empty with a HTTP status code of 102 Processing until job has completed. Jobs will be held for 1 hour after completion before result is deleted.

Status: 200 OK
{
    "expires": "2017-03-30 12:58:45 UTC",
    "report": "https:\/\/bucket-name.s3.eu-west-2.amazonaws.com\/environment\/environment-user-report-20170323-125844-jdu923mc.zip?X-Amz-Algorithm=AWS4-HMAC-SHA256\u0026X-Amz-Credential=AKIAJ6R4WNSL4LXJNERA%2F20170323%2Feu-west-2%2Fs3%2Faws4_request\u0026X-Amz-Date=20170323T125845Z\u0026X-Amz-SignedHeaders=Host\u0026X-Amz-Expires=604800\u0026X-Amz-Signature=2757a0fe99f95759cb64e9f31a13c0d53f29d5e94851e1b52bdbab615dd"
}