---
title: "Create a user"
method: POST
path: "/payout/user"
tags: ["User"]
---

# Create a user

`POST /payout/user`

This **POST** endpoint is used to create a new user in MassPay. <br> You can use this endpoint to create a new user with the specified user details in JSON format in the request Body. <br> To use this endpoint, you need to provide the `internal_user_id`, `country`, `first_name`, `last_name`, and `email` as required parameters in the Request Body. <br> The response will include details about the newly created user.

## Request body

- User
  - `internal_user_id` string, required — A client-defined identifier for the user. This is the unique ID assigned to the user on your system. Max 75 characters. Allows letters, numbers, and + , - . / _ ~ |
  - `address1` string — The user's street address. Required in order to process a payout.
  - `address2` string — The user's street address, line 2.
  - `city` string — The user's city. Required in order to process a payout.
  - `state_province` string — The user's state/province.
  - `postal_code` string — The user's postal code.
  - `country` string, required — The user's country code. [ISO_3166](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) code. Required in order to process a payout.
  - `first_name` string, required — The user's first name. (If Business account, the first name of the representative)
  - `middle_name` string — The user's middle name. (If Business account, the middle name of the representative)
  - `last_name` string, required — The user's last name. (If Business account, the last name of the representative)
  - `email` string, required — The user's e-mail address. Must be unique. Cannot have two users with the same e-mail address.
  - `language` string — The user's preferred language of communication. If not provided, defaults to English (en)
  - `mobile_number` string — (Optional) Mobile number of user. Allows for SMS notifications upon availability of funds
  - `business_name` string — Company legal name (Only if Business account)
  - `date_of_birth` string, date — Date of birth. Optional when creating a user, but required before processing a payout unless explicitly exempted by compliance. Users must be at least 18 years old, unless a lower age is approved by compliance.
  - `metadata` object — Optional JSON object with attributes that can later be searched to locate this user. Do not include PII as this object is not encrypted.
    - `group_id` number
  - `notify_user` boolean — Should we notify the user via email that their user has been created in the system? They will receive instructions to establish such account.

## Response `201`

Successfully created.

- StoredUser
  - `user_token` string, uuid, required — Token representing the user that was just created
  - `status` 'ACTIVE' | 'LOCKED' | 'DEACTIVE' | 'CLOSED', required — The status of the user
  - `created_on` string, YYYY-MM-DDThh:mm:ss, required — The timestamp the user was created in the system. Using UTC timestamp.[ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)
  - `internal_user_id` string, required — A client-defined identifier for the user. This is the unique ID assigned to the user on your system. Max 75 characters. Allows letters, numbers, and + , - . / _ ~ |
  - `address1` string — The user's street address.
  - `address2` string — The user's street address, line 2.
  - `city` string — The user's city.
  - `state_province` string — The user's state/province.
  - `postal_code` string — The user's postal code.
  - `country` string — The user's country code. ISO_3166-1_alpha-3 code
  - `first_name` string, required — The user's first name. (If Business account, the first name of the representative)
  - `middle_name` string — The user's middle name. (If Business account, the middle name of the representative)
  - `last_name` string, required — The user's last name. (If Business account, the last name of the representative)
  - `email` string, required — The user's e-mail address. Must be unique. Cannot have two users with the same e-mail address.
  - `language` string — The user's preferred language of communication. If not provided, defaults to English (en)
  - `mobile_number` string — (Optional) Mobile number of user. Allows for SMS notifications upon availability of funds
  - `business_name` string — Company legal name (Only if Business account)
  - `timezone` string, required — User's computed timezone
  - `date_of_birth` string, date — Date of birth. (optional). Minimum 18 years old
  - `metadata` object — Optional JSON object with attributes that can later be searched to locate this user. Do not include PII as this object is not encrypted.
  - `activation_url` string — If the user does not have an activated account yet, an activation URL will be provided.

## Other responses

- `400` — Bad request.
- `401` — Unauthorized.
- `403` — Forbidden.
- `404` — Not found.
- `405` — Method Not Allowed.
- `500` — Internal server error.
- `504` — Gateway Time-out.

---

[API](https://skmtc.net/masspay/apis/masspay-api.md) · [All operations](https://skmtc.net/masspay/apis/masspay-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/masspay/masspay-api/revisions/c03b61a6a551/schema)