Create, Upgrade and Downgrade Deputy Embedded Accounts

Provisioning a Deputy Account

The first step in the provisioning flow is to create a Deputy business. A Deputy business is designed to match one account on the partner system. Multiple locations can be created under a Deputy business.

To create a business, submit a post request to the signup endpoint

πŸ“˜

Bearer Token

You will need to pass in a bearer token (created here https://dash.readme.com/project/deputy-docs/v1.0/docs/provisioning-api-security-overview) in order to access all of these provisioning APIs.

URL

curl POST https://api.usw2.deputy.com/connect/v1/partner/{partnername}/signup

{partnername} is the name we assign to the partner's embedded integration.

Sample Request Payload

{
    "userData": {
        "firstName": "Deputy",
        "lastName": "User",
        "email": "[email protected]",
        "mobileNumber": "+61 00000000"
    },
    "businessData": {
        "externalId": "Biz1",
        "estimatedEmployeeCount": "15",
        "portfolioName": "Calvins Coffee",
    }
}

Data Elements

userData

Data ElementMandatoryInfo
firstNameYesThe first name of the user creating a Deputy Trial.
lastNameYesThe last name of the user creating a Deputy Trial.
emailYesThe email address of a user creating a Deputy trial. For Embedded customers, this account must be new to Deputy otherwise an error will be thrown.
mobileNumberNoThe mobile number of the user signing up to Deputy. This needs to be a valid mobile number otherwise an error will be thrown.

businessData

Data ElementMandatoryInfo
externalIdYesA partner provided external ID. We store this internally to create a mapping between the Deputy embedded account and the user's account on the partner's app. This is freetext and must be unique.
estimatedEmployeeCountNoAn integer representing the estimated number of customers that will be onboarded into Deputy. Value must be greater than 0.
portfolioNameYesThe business name shows internally in several places in the product.

This will create Deputy which lasts 30 days. An account must be converted within these 30 days via a call to our conversion endpoint.

🚧

Geolocation

The Deputy business will be created in the root region of the API call. Our current provisioning API runs in the US region only (https://api.usw2.deputy.com) , however UK ( https://api.euw2.deputy.com) and AU (https://api.apse2.deputy.com) are in development.

Response

The response from this endpoint will detail the following fields

{  
    "success": true,  
    "data": {  
        "hostname": "biz.na.deputy.com",  
        "portfolioName": "Calvins Coffee",  
        "status": "ACTIVE",  
        "edition": "SUBSCRIPTION_PRO_TRIAL",  
        "trialEndDate": "2023-05-13T00:00:00.000Z",  
        "conversionDate": "",  
        "externalId": "Biz1"  
    },  
    "error": null  
}

Data Elements Returned

Data ElementInfo
hostnameThe URL of the created Deputy account.
portfolioNameThe portfolio name provided in the post request.
statusAlways ACTIVE indicating an Active Deputy installation.
editionAlways SUBSCRIPTION_PRO_TRIAL, indicating a Deputy trial for a Premium monthly subscription.
trialEndDateDate the Deputy accounts trial ends. The account should be converted before this date.
conversionDateAlways empty at this point in time.
externalIdThe external ID provided in the request.

Converting or Cancelling a Deputy Account

To convert an account to a premium Deputy subscription OR cancel a Deputy subscription, a POST request needs to be made to the change-plan endpoint.

URL

curl POST https://api.usw2.deputy.com/connect/v1/partner/{partnername}/change-plan

🚧

Business Address Requirements

If you're converting an account in the US, extra data containing the billing address of the business is required for compliance reasons.

Sample Request Payload to Convert

{  
    "data" : {  
        "hostname": "biz.na.deputy.com",  
        "action": "upgrade",
      	"address": {
            "address1": "123 Elm Street",
            "suburb": "Manhattan",
            "state": "NY",
            "postcode": "12345",
            "country": "US"
        }
    }  
}

Sample Request Payload to Cancel

{  
    "data" : {  
        "hostname": "biz.na.deputy.com",  
        "action": "cancel"
    }  
}

Data Elements

Data

Data ElementMandatoryInfo
hostnameYesA valid hostname, returned as part of the provisioning endpoint.
actionYesEither upgrade or cancel

Address

Data ElementMandatoryInfo
address1NoA valid street address.
suburbNoCity or suburb
stateNoState to which the address belongs to
postcodeNoPostal code of the address
countryNoCountry to which the address belongs to

The response from this endpoint will detail the following fields

{  
    "success": true,  
    "data": {  
        "hostname": "biz.na.deputy.com",  
        "trialEndDate": "2023-05-14T00:00:00+00:00",  
        "edition": "SUBSCRIPTION_PAID_PRO_PREMIUM"  
    },  
    "error": null  
}

Data Elements Returned

Info

Data ElementInfo
hostnameThe URL of the created Deputy account.
trialEndDateThe date that the trial ends. If converting before the end date of the trial, the day after the end of trial will constitute the start of billing.
editionThe edition the account has been converted to.

Note An error will be thrown if you try to upgrade an account that is already Premium, or cancel an account that is on trial or expired.

First Time Setup

A default location with the same name as the business will be default created. If the location name needs to be different from the business name, a call to the locations endpoint https://developer.deputy.com/deputy-docs/reference/updatealocation is needed to update the name and other details.

In addition, for Deputy to work correctly, an area needs to be created inside a location. You are able to create a location by calling the departments endpoint https://developer.deputy.com/deputy-docs/reference/createadepartment

Status Check on a Deputy business.

To retrieve subscription information related to a Deputy installation, a POST request can be made to the Status Check endpoint

URL

curl POST https://api.usw2.deputy.com/connect/v1/partner/{partnername}/subscription-status

Sample Payload

{  
    "hostname": "biz.na.deputy.com"  
}

Data elements

Data ElementMandatoryInfo
hostnameYesA valid hostname, returned as part of the provisioning endpoint.

Response

Given a hostname that is linked to the partner making the request, the endpoint will return

{  
    "success": true,  
    "data": {  
        "status": "ACTIVE",  
        "hostname": "biz.na.deputy.com",  
        "portfolioName": "Calvins Coffee",  
        "edition": "SUBSCRIPTION_FREE",  
        "trialEndDate": "2023-05-05T00:00:00.000Z",  
        "conversionDate": ""  
    },  
    "error": null  
}

Note on Embedded Subscription Editions

Deputy embedded accounts have three editions

  • SUBSCRIPTION_PRO_TRIAL - The account is in a trial state. The trial will expire at the date listed in the trialEndDate field. Trials should be converted before this date.
  • SUBSCRIPTION_FREE - a premium account has been cancelled, or a trial has expired. SUBSCRIPTION_FREE accounts may be converted into SUBSCRIPTION_PAID_PRO_PREMIUM accounts via calling our change plan endpoint. While in a SUBSCRIPTION_FREE state, these accounts may be deleted by Deputy, especially if the account has low users and has been dormant. For this reason, it's recommended to convert before the account enters this state, or soon after.
  • SUBSCRIPTION_PAID_PRO_PREMIUM - a paid, converted Deputy account.