> For the complete documentation index, see [llms.txt](https://beprepared.gitbook.io/beprepared/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://beprepared.gitbook.io/beprepared/clients.md).

# Clients

Create clients, confirm their vaults, and suspend or permit access.

Using the BePrepared API, you are able to create secure digital legacy vaults quickly and easily.

A new vault is automatically generated for you each time you create a client, and connected with that client record.

### <mark style="background-color:blue;">The Client Object</mark>

The client object has the following attributes

<details>

<summary>Client <em>Object</em></summary>

#### Example

```javascript
{
	"id" : "client_kjslkdjs8947wkjhw4hjhJKH",
	"firstName" : "Jane",
	"lastName" : "Doe",
	"email" : "janedoe@test.com",
	"dateOfBirth" : {
			"day" : 10,
			"month" : 3,
			"year" : 1993
	},
	"connected" : false,
	"accessToVault" : true,
	"mainProvider" : false,
	"userRevokedAccess" : false,
	"status" : "draft",
	"statusReason" : "Secondary Rep",
	"inviteUrl" : null, 
	"inviteClientEndpoint" : "client/id/invite",
	"confirmCreationEndpoint" : "v1/clients/client_kjslkdjs8947wkjhw4hjhJKH/confirm",
	"releaseTracker" : null,
	"createdAt" : "2022-05-16T11:36:26.584+00:00",
	"updatedAt" : "2022-05-16T11:36:26.584+00:00"
```

**id** *<mark style="color:orange;">string</mark>*

Unique identifier of the object.

**firstName** *<mark style="color:orange;">string</mark>*

The first name of the client.

**lastName** *<mark style="color:orange;">string</mark>*

The last name of the client.

**email** *<mark style="color:orange;">string</mark>*

The email of the client. It must be a valid email.

**mobileNumber** *<mark style="color:orange;">string</mark>*

The mobile number of the client is in international format. i.e it begins with '+XX'

**dateOfBirth** *<mark style="color:red;">object</mark>* *<mark style="color:green;">DateOfBirth</mark>*

On object representing the birth date of the client.

&#x20;   **dateOfBirth.day** *<mark style="color:green;">number</mark>*

&#x20;   The day of the month.

&#x20;   **dateOfBirth.month** *<mark style="color:green;">number</mark>*

&#x20;   The month of the year.

&#x20;   **dateOfBirth.year** *<mark style="color:green;">number</mark>*

&#x20;   The year of the birth.

**connected** *<mark style="color:blue;">boolean</mark>*

Represents whether or not the user associated with the client has signed up.

**accessToVault** *<mark style="color:blue;">boolean</mark>*

Represents whether or not the client has access to the vault. Main providers have the capability to suspend and grant their client’s access to their vault.

**mainProvider** *<mark style="color:blue;">boolean</mark>*

Represents wether or not a business is the main provider of a Prepared Vault to someone with the same email address.

**userRevokedAccess** *<mark style="color:blue;">boolean</mark>*

Represents whether or not a user has revoked the business access to their vault. A user can not revoke the access of their main provider.

**status** *<mark style="color:purple;">enum</mark>*

Indicates whether or not the client object’s creation is completed or whether something needs to be confirmed before proceeding.

Possible enum values include:

* draft - This client creation has not been completed.
* active - This client creation has completed.

**statusReason** *<mark style="color:purple;">enum</mark>*

Explains the reason the client object was created as a draft.

Possible enum values include:

* Secondary\_Rep - This client has the same email as an existing user in the the prepared system. Confirmation is needed due to the reduced functionality as continuing as a Secondary Representative.

**inviteUrl** *<mark style="color:orange;">string</mark>*

The url that a client can use to create and account and sign up. This will only be populated if the client status is active and the client has not signed up yet.

**inviteClientEndpoint** *<mark style="color:orange;">string</mark>*

The url endpoint to call to initiate the sending of an invite url to the client using The Prepared Company’s default email templates. This will only be populated if the client status is active and the client has not signed up yet.

**confirmCreationEndpoint** *<mark style="color:orange;">string</mark>*

The url endpoint to call if you would like to confirm the creation of a client. This will only be populated if the client status is draft.

**releaseTracker** *<mark style="color:red;">object</mark>*

An object containing details of the release tracker. This will only contain data if the client has been reported deceased.

&#x20;   **releaseTracker.active** *<mark style="color:blue;">boolean</mark>*

&#x20;   Wether or not the release tracker is valid and running.

&#x20;   **releaseTracker.reporter** *<mark style="color:blue;">boolean</mark>*

&#x20;   Unique identifier of the representative or confidant that reported the death.

&#x20;   **releaseTracker.currentStage** *<mark style="color:purple;">enum</mark>*

&#x20;   Identifies the stage the release tracker is in.

**createdAt** *<mark style="color:green;">timestamp</mark>*

A timestamp of when the client was created as UTC time.

**updatedAt** *<mark style="color:green;">timestamp</mark>*

A timestamp of when this client object was last updated as UTC time.

</details>

### <mark style="background-color:blue;">Creating a New Client</mark>

Creating a new client is the most fundamental function you will perform with our API.

Depending on your business case, the most important question you must answer is if you'll be automatically approving each new vault request (for example, if you create the vault after a checkout flow), or if some condition needs to be met before approval (for example, if you're running a waitlist).

#### Code Example

{% tabs %}
{% tab title="Node.js" %}

```javascript
import axios from 'axios'

axios.post('/YOUR_API_URLv1/clients', {
      headers: { 'Authorization': 'Bearer API_KEY'},
      {
        firstName: 'John',
        lastName: 'Smith',
        email: 'example@domain.com',
        dateOfBirth: {
          day: 30,
          month: 12,
          year: 1992
        }
      }).then(res => {
      console.log(res);
    }).catch( err => {
      console.log(err);
    });
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = '/YOUR_API_URLv1/clients'
headers = {'Authorization': 'Bearer API_KEY'}
data = {
    'firstName': 'John',
    'lastName': 'Smith',
    'email': 'example@domain.com',
    'dateOfBirth': {
        'day': 30,
        'month': 12,
        'year': 1992
    }
}

response = requests.post(url, headers=headers, json=data)

if response.status_code == 200:
    print(response.json())
else:
    print(response.status_code)

```

{% endtab %}

{% tab title="cURL" %}

```bash
curl -X POST -H "Authorization: Bearer API_KEY" -H "Content-Type: application/json" -d '{
    "firstName": "John",
    "lastName": "Smith",
    "email": "example@domain.com",
    "dateOfBirth": {
        "day": 30,
        "month": 12,
        "year": 1992
    }
}' 'YOUR_API_URLv1/clients'

```

{% endtab %}
{% endtabs %}

#### Request Details

## Create a client and loads a vault

<mark style="color:green;">`POST`</mark> `YOUR_API_URLv1/clients`

#### Query Parameters

| Name        | Type    | Description                                                                                                      |
| ----------- | ------- | ---------------------------------------------------------------------------------------------------------------- |
| autoApprove | Boolean | Determines if you want to accept this new vault creation request or not. Either true or false. Defaults to false |

#### Headers

| Name                                            | Type   | Description        |
| ----------------------------------------------- | ------ | ------------------ |
| Authorization<mark style="color:red;">\*</mark> | String | Bearer \<API\_KEY> |

#### Request Body

| Name                                        | Type   | Description                               |
| ------------------------------------------- | ------ | ----------------------------------------- |
| firstName<mark style="color:red;">\*</mark> | String | First name of client.                     |
| lastName<mark style="color:red;">\*</mark>  | String | Last name of client                       |
| email<mark style="color:red;">\*</mark>     |        | Email address of client                   |
| dateOfBirth                                 | Object | Object containing date of birth of client |
| dateOfBirth.day                             | Number | Day of the month client was born          |
| dateOfBirth.month                           | Number | Month of the year client was born         |
| dateOfBirth.Year                            | Number | Year that the client was born             |

{% tabs %}
{% tab title="201: Created Returns a Client in the client property." %}

```javascript
{
		"client" : {
		"id" : "client_kjslkdjs8947wkjhw4hjhJKH",
		"firstName" : "Jane",
		"lastName" : "Doe",
		"email" : "janedoe@test.com",
		"mobileNumber" : null,
		"dateOfBirth" : {
				"day" : 10,
				"month" : 3,
				"year" : 1993
		},
		"connected" : false,
		"accessToVault" : true,
		"mainProvider" : false,
		"userRevokedAccess" : false,
		"status" : "draft",
		"statusReason" : "Secondary Rep",
		"inviteUrl" : null, 
		"inviteClientEndpoint" : null,
		"confirmCreationEndpoint" : "v1/clients/client_kjslkdjs8947wkjhw4hjhJKH/confirm",
		"releaseTracker" : null,
		"createdAt" : "2022-05-16T11:36:26.584+00:00",
		"updatedAt" : "2022-05-16T11:36:26.584+00:00"
	}
}
```

{% endtab %}
{% endtabs %}

### <mark style="background-color:blue;">Confirming Client Creation</mark>

Depending on your implimentation, you'll either be automatically confirming all clients, or approving clients before their vaults are created. This route is to be used if autoApprove param is false in the client creation route.

#### Code Example

{% tabs %}
{% tab title="Node.js" %}

```javascript
import axios from 'axios'

axios.post('YOUR_API_URL/v1/clients/:clientId/confirm', {
      headers: { 'Authorization': 'Bearer API_KEY'},
      {}).then(res => {
      console.log(res);
    }).catch( err => {
      console.log(err);
    });
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

headers = {'Authorization': 'Bearer API_KEY'}

response = requests.post('YOUR_API_URL/v1/clients/:clientId/confirm', headers=headers)

if response.status_code == 200:
    print(response.json())
else:
    print(response.text)

```

{% endtab %}

{% tab title="cURL" %}

```bash
curl -X POST 'YOUR_API_URL/v1/clients/:clientId/confirm' \
-H 'Authorization: Bearer API_KEY'
```

{% endtab %}
{% endtabs %}

#### Request Details

## Transfers a client from draft status to active

<mark style="color:green;">`POST`</mark> `YOUR_API_URL/v1/clients/:clientId/confirm`

#### Path Parameters

| Name                                       | Type   | Description                          |
| ------------------------------------------ | ------ | ------------------------------------ |
| clientId<mark style="color:red;">\*</mark> | String | ID associated with the client record |

#### Headers

| Name          | Type   | Description        |
| ------------- | ------ | ------------------ |
| Authorization | String | Bearer \<API\_KEY> |

{% tabs %}
{% tab title="200: OK Returns a Client in the client property." %}

```javascript
{
	"client" : {
		"id" : "client_kjslkdjs8947wkjhw4hjhJKH",
		"firstName" : "Jane",
		"lastName" : "Doe",
		"email" : "janedoe@test.com",
		"mobileNumber" : "+61485493282",
		"dateOfBirth" : {
				"day" : 10,
				"month" : 3,
				"year" : 1993
		},
		"connected" : false,
		"accessToVault" : true,
		"mainProvider" : false,
		"userRevokedAccess" : false,
		"status" : "active",
		"statusReason" : null,
		"inviteUrl" : "dummy/inviteurl/ksjfdslfje",
		"inviteClientEndpoint" : "client/id/invite", 
		"confirmCreationEndpoint" : null,
		"releaseTracker" : null,
		"createdAt" : "2022-05-16T11:36:26.584+00:00",
		"updatedAt" : "2022-05-16T11:36:26.584+00:00"
	}
}
```

{% endtab %}
{% endtabs %}

### <mark style="background-color:blue;">Suspending Client Access</mark>

Sometimes you might wish to suspend client access, such as in the case of the ending of a free trial, or due to non-payment.

You can use the suspend route to temporarily prevent client access to the vault in these circumstances.

#### Code Example

{% tabs %}
{% tab title="Node.js" %}

```javascript
import axios from 'axios'

axios.patch('YOUR_API_URL/v1/clients/:clientId/access/suspended', {
      headers: {
        'Authorization': 'Bearer API_KEY'
      },
      {}).then(res => {
      console.log(res);
    }).catch(err => {
      console.log(err);
    });
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

headers = {'Authorization': 'Bearer API_KEY'}

response = requests.patch('YOUR_API_URL/v1/clients/:clientId/access/suspended', headers=headers)

if response.status_code == 200:
    print(response.json())
else:
    print(response.text)

```

{% endtab %}

{% tab title="cURL" %}

```bash
curl -X PATCH 'YOUR_API_URL/v1/clients/:clientId/access/suspended' \
-H 'Authorization: Bearer API_KEY'

```

{% endtab %}
{% endtabs %}

#### Request Details

## Suspends a clients access to their vault.

<mark style="color:purple;">`PATCH`</mark> `YOUR_API_URL/v1/clients/:clientId/access/suspended`

This can only be completed by the client’s main provider.

#### Path Parameters

| Name                                       | Type   | Description                           |
| ------------------------------------------ | ------ | ------------------------------------- |
| clientId<mark style="color:red;">\*</mark> | String | ID associated with the client record. |

#### Headers

| Name                                            | Type   | Description        |
| ----------------------------------------------- | ------ | ------------------ |
| Authorization<mark style="color:red;">\*</mark> | String | Bearer \<API\_KEY> |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
	"suspended": true
}
```

{% endtab %}
{% endtabs %}

### <mark style="background-color:blue;">Restoring Client Access</mark>

The purpose of this route is to restore access to a clients vault if they proceed to a paid plan post free trial, or account invoices are no longer overdue.

#### Code Example

{% tabs %}
{% tab title="Node.js" %}

```javascript
import axios from 'axios'

axios.patch('YOUR_API_URL/v1/clients/:clientId/access/granted', {
      headers: {
        'Authorization': 'Bearer API_KEY'
      },
      {}).then(res => {
      console.log(res);
    }).catch(err => {
      console.log(err);
    });
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

headers = {'Authorization': 'Bearer API_KEY'}

response = requests.patch('YOUR_API_URL/v1/clients/:clientId/access/granted', headers=headers)

if response.status_code == 200:
    print(response.json())
else:
    print(response.text)

```

{% endtab %}

{% tab title="cURL" %}

```bash
curl -X PATCH 'YOUR_API_URL/v1/clients/:clientId/access/granted' \
-H 'Authorization: Bearer API_KEY'

```

{% endtab %}
{% endtabs %}

#### Request Details

## Removes client’s suspended, thereby granting them access to their vault.&#x20;

<mark style="color:purple;">`PATCH`</mark> `YOUR_API_IRL/v1/clients/:clientId/access/granted`

This can only be completed by a client’s main provider.

#### Path Parameters

| Name                                       | Type   | Description                          |
| ------------------------------------------ | ------ | ------------------------------------ |
| clientId<mark style="color:red;">\*</mark> | String | ID associated with the client record |

#### Headers

| Name                                            | Type   | Description        |
| ----------------------------------------------- | ------ | ------------------ |
| Authorization<mark style="color:red;">\*</mark> | String | Bearer \<API\_KEY> |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
	"suspended": false
}
```

{% endtab %}
{% endtabs %}