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://developer.deputy.com/deputy-docs/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",
        "countryCode": "AU",
    }
}

Data Elements

userData

businessData

This will create a Deputy Premium trial 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

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

Address

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

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.

Status Check on a Deputy Business

To retrieve subscription information related to a Deputy business, 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

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.