# Tutorial: Manage new user accounts

This tutorial demonstrates how to create and locate user accounts.
It also creates or recalls the user account IDs that the tutorials use to demonstrate other Tilia services.

Allow about 15 minutes to complete this tutorial.

### API operations in this tutorial

| Tutorial interaction | API operation used | Scope | Environment variables initialized |
|  --- | --- | --- | --- |
| [Create new users](#create-new-users) |  | `write_registrations` | `payers_account_id``recipients_account_id``creators_account_id` |
| [Recall existing users](#recall-existing-users) |  | `search_accounts` | `payers_account_id``recipients_account_id``creators_account_id` |


This tutorial uses the **_Manage user accounts** collection from the
[shared workspace](https://www.postman.com/tilia-docs-testing/workspace/get-started-using-tilia-services/overview).

To complete this tutorial successfully:

1. Make sure the software described in [Get started with the tutorials](/tutorials/tutorial_get_started)
has been installed on your system and configured.
2. In Postman:
  1. Open the **Tilia tutorial workspace** you created in [Get started with the tutorials](/tutorials/tutorial_get_started).
  2. Make sure you have the **_Manage user accounts** collection forked to your **Tilia tutorial workspace**.
  3. Make sure that you've selected the **Tilia Client Info** environment and confirmed that it has:
    1. Your Tilia developer credentials.
    2. The usernames and email addresses for your users: payer, recipient,
and creator, if you're creating new users; or usernames for your users if you are recalling existing accounts.
  4. In your **Tilia tutorial workspace**, open the list of **Collections**.
  5. In the list of **Collections**, expand the **_Manage user accounts** collection.
  6. If it's been more than an hour since you last got an access token for this collection,
get a new one as described in [Tutorial: User accounts overview](#),
and then return to continue here.


## Create new users

This exercise creates new user accounts for the users described in the environment variables.

These requests create new user accounts and are found in the **_Manage user accounts** collection,
in the **Create new users** folder:

- **Add payer's user account**
- **Add recipient's user account**
- **Add creator's user account**


The requests are identical with the exception of the request body, which is specific to the user being added.

Note about the payer
Your payer can use regular payment methods in their Tilia transactions, or the payer
can use an [external payment platform](/guides/external-payment-platforms).
You must decide which, at the time you create their user account.

If your payer is using:

- **Regular payment methods**, continue in this exercise and skip
**Create payer from an external platform**.
- **An external payment platform**, use this exercise to create only the recipient and creator accounts,
and then skip to [Create the payer's account from an external payment platform](#create-the-payers-account-from-an-external-payment-platform)
and continue on from there.


Repeat this procedure for each user account to add.

**For each user account to add, in Postman:**

1. In the **_Manage user accounts** collection, in the **Create new users** folder, open the request to add the user,
and then choose the **Body** tab.
2. In the request **Body** tab, shown here, notice that the `username` and
`email.address` properties use the environment variables
you edited when getting started.

```json
{
    "username": "{{users_username}}",
    "email": { 
        "address": "{{users_email}}"
    }
}
```
3. Choose **Send** to create a new user account.
A typical response body looks like the following.

```json
{
    "status": "Success",
   "message":[],
   "codes":[],
   "payload": {
        "account_id": "acct_2ZB8jw5SS0NATzMDvn7NcG4XtVT",
        "username": "user_602"
    }
}
```
If successful, the **Current value** of the user's account ID environment variable
is updated with the `account_id` from the `payload` of the response body.


## Create the payer's account from an external payment platform

This exercise demonstrates how to add a user account for the payer when the payer is a user from one
of Tilia's supported external payment platforms.

Tilia can collect funds from external payment platforms to use in Tilia transactions.
This gives your users access to Tilia transactions from apps that must process payments through a vendor's app store.

Such user accounts must provide the user account information from the external payment platform when
their Tilia user account is created.

Note
The account created by this exercise replaces any existing payer account in the Postman environment.

**To create the payer's account from an external payment platform:**

1. In the **_Manage user accounts** collection, in the **Payer from external platform** folder,
open the **Add payer from external platform** request, and then choose the **Body** tab.
2. In the request **Body** tab, shown here, notice that the `username` and
`external_platforms` properties use the environment variables
you edited when getting started.
Also notice that instead of an `email`, the `external_platforms` property is used to identify the user.
For this exercise, the `payers_email` is used as the user's ID in the external payment platform.

```json
{
    "username": "{{payers_username}}",
    "external_platforms": {
        "apple": {
            "user_id": "{{payers_email}}"
        }
    }
}
```
3. Choose **Send** to create a new user account.
A typical response body looks like the following.

```json
{
    "status": "Success",
   "message":[],
   "codes":[],
   "payload": {
        "account_id": "acct_2ZB8jw5SS0NATzMDvn7NcG4XtVT",
        "username": "user_602"
    }
}
```
If successful, the **Current value** of the user's account ID environment variable
is updated with the `account_id` from the `payload` of the response body.


The payer already has a payment method defined that uses the external payment platform.
With this, you can skip to the
[Get payer's payment method](/tutorials/user-accounts/tutorial_user_buy_tokens#get-payers-payment-methods) procedure and
run the procedure for payers from external platforms.

## Recall existing users

This exercise recalls existing user accounts whose usernames are described in the environment variables.

If you just added the users in the previous exercise, this exercise is not required.
However, you still run it to see how the  operation
works without any problems.

These requests search for existing user accounts by looking up the username, and are
found in the **_Manage user accounts** collection, in the **Recall existing users** folder.

- **Recall payer's user account**
- **Recall recipient's user account**
- **Recall creator's user account**


Each request is identical to the other, with the exception of the username parameter,
which is specific to the user being recalled.

Repeat this procedure for each user request in the **Recall existing users** folder.

**For each existing user to look up by using the user's username, in Postman:**

1. In the **_Manage user accounts** collection, in the **Recall existing users** folder, open the request to add the user,
and then choose the **Params** tab.
2. In the **Params** tab, notice that the `username` parameter uses the environment variable with the user's username.
3. In the request, choose **Send**.
4. After the response returns, below the request, open the response **Body** tab to review details of the response body.


A typical response body looks like the following.


```json
{
    "status": "Success",
    "message": [],
    "codes": [],
    "payload": {
        "account_id": "acct_2ZB8jw5SS0NATzMDvn7NcG4XtVT",
        "username": "payer_602",
        "email": "payer_602@example.com",
        "is_blocked": false,
        "blocked_capabilities": {},
        "integrator": "tilia-test",
        "tags": [],
        "created": "2023-12-06T17:37:30.68692Z"
    }
}
```

If successful, a script runs after the response returns to save the `account_id` in
the user's account ID environment variable.

A status of `404` and a response body similar to this one means that an account wasn't found
with the username you entered in the environment variables for that user.


```json
{
    "status": "Failure",
    "message": [
        "failed to get account"
    ],
    "codes": [
        "ACCOUNT_GET_ERROR"
    ],
    "payload": null
}
```

To correct this, correct the username in the environment variables or
create a new user.

## Next steps

To get information about a user's account when you already have their account ID,
the  operation
returns the same payload as the  operation.

With the user accounts initialized, your next step is [Buy tokens](/tutorials/user-accounts/tutorial_user_buy_tokens)
so the payer has tokens to use in future transactions.