> ## Documentation Index
> Fetch the complete documentation index at: https://diameterpay.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Create an Individual End User

> POST /v1/end-users/individuals — Creates a new individual end user and initiates bank onboarding. Requires end-users.write scope.

Creating an individual end user registers a person on the Diameter platform and immediately kicks off the bank onboarding process for each bank partner you specify. Once the asynchronous onboarding completes, the `onboardedInBanks` array is populated and the `onboardingStatus` transitions away from `INACTIVE`. Use the returned `id` to reference this end user in all subsequent API calls.

## Endpoint

```
POST /v1/end-users/individuals
```

**Required scope:** `com.diameterpay.api/end-users.write`

## Request Headers

**Authorization** `string` *required*

Bearer token obtained from your OAuth 2.0 token endpoint. Format: `Bearer {access_token}`

**x-idempotency-key** `string` *required*

A UUID v4 string you generate for each unique request. Re-sending the same key within the idempotency window returns the original response without creating a duplicate end user.

## Request Body

### Required Fields

**productId** `string` *required*

UUID v4 of the Diameter product to associate with this end user.

**firstName** `string` *required*

Individual's legal first name.

**lastName** `string` *required*

Individual's legal last name.

**email** `string` *required*

Individual's email address. Must be a valid email format.

**mobilePhone** `string` *required*

Mobile phone number in E.164 format (e.g. `+12125551234`).

**dateOfBirth** `string` *required*

Date of birth in `YYYY-MM-DD` format (e.g. `1990-07-15`).

**nationality** `string` *required*

ISO 3166-1 alpha-2 country code representing the individual's nationality (e.g. `US`, `DE`, `GB`).

**idType** `string` *required*

Type of government-issued identification. One of: `PASSPORT`, `DRIVING_LICENSE`, `NATIONAL_ID_CARD`, `SSN`, `ITIN`, `EIN`, `OTHER_ID`.

**idNumber** `string` *required*

The identifier number on the chosen identity document.

**idCountry** `string` *required*

ISO 3166-1 alpha-2 country code that issued the identity document.

**pepStatus** `string` *required*

Politically Exposed Person status. One of: `YES`, `NO`.

**primaryAddress** `object` *required*

The individual's primary residential address.

**primaryAddress fields**

**addressType** `string` *required*

Address type label (e.g. `RESIDENTIAL`, `BUSINESS`).

**country** `string` *required*

ISO 3166-1 alpha-2 country code.

**postalCode** `string` *required*

Postal or ZIP code.

**townName** `string` *required*

City or town name.

**streetName** `string` *required*

Street name (without building number).

**buildingNumber** `string`

Building or house number.

**countrySubdivision** `string`

State, province, or region (e.g. `NY`, `CA`).

**district** `string`

District or borough.

**floor** `string`

Floor number within a building.

**room** `string`

Room or apartment number.

**department** `string`

Department name (used in some address formats).

**subDepartment** `string`

Sub-department name.

**postOfficeBox** `string`

PO Box identifier.

**onboardInBanks** `array` *required*

List of bank partners to onboard this end user with. Accepted values: `PORTAGE`, `SLOVAK_SAVINGS_BANK`.

### Optional Fields

**middleName** `string`

Individual's middle name. When provided, it is included in the auto-built `fullName`.

**internalEndUserIdentifier** `string`

Your system's internal identifier for this user. Maximum 255 characters. Useful for correlating Diameter records with your own database.

**internalEndUserActivity** `integer`

Numeric code representing the end user's business activity in your system.

**internalEndUserStartDate** `string`

The date this user became active in your system (`YYYY-MM-DD`).

**gender** `string`

Individual's gender. One of: `MALE`, `FEMALE`.

**mailingAddress** `object`

Mailing address if different from `primaryAddress`. Accepts the same fields as `primaryAddress`.

> [!NOTE]
>
> `fullName` is **deprecated as an input field**. It is automatically constructed by concatenating `firstName`, `middleName` (if provided), and `lastName`. Any value you send for `fullName` in the request body is ignored.

## Response

Returns `201 Created` with the newly created `IndividualEndUserOutput` object.

**id** `string`

Diameter-assigned UUID v4 for this end user. Use this in all subsequent requests.

**productId** `string`

UUID of the associated product.

**firstName** `string`

Individual's first name.

**middleName** `string`

Individual's middle name, if provided.

**lastName** `string`

Individual's last name.

**fullName** `string`

Auto-built full name combining `firstName`, optional `middleName`, and `lastName`.

**email** `string`

Individual's email address.

**mobilePhone** `string`

Mobile phone in E.164 format.

**dateOfBirth** `string`

Date of birth in `YYYY-MM-DD` format.

**nationality** `string`

ISO 3166-1 alpha-2 nationality code.

**idType** `string`

Identity document type.

**idNumber** `string`

Identity document number.

**idCountry** `string`

ISO 3166-1 alpha-2 code of the country that issued the ID.

**pepStatus** `string`

PEP status: `YES` or `NO`.

**gender** `string`

Gender, if provided.

**onboardingStatus** `string`

Overall onboarding status. Starts as `INACTIVE` immediately after creation; transitions as bank onboarding progresses.

**onboardedInBanks** `array`

List of bank partners where onboarding has completed. Empty immediately after creation.

**addresses** `array`

Array of address objects associated with this end user, including `primaryAddress` and optional `mailingAddress`.

**internalEndUserIdentifier** `string`

Your internal identifier, if provided.

**internalEndUserActivity** `integer`

Internal activity code, if provided.

**internalEndUserStartDate** `string`

Internal start date, if provided.

**createdAt** `string`

ISO 8601 timestamp of when the end user was created.

**updatedAt** `string`

ISO 8601 timestamp of the most recent update.

## Example Request

```bash theme={null}
curl --request POST \
  --url https://api.sandbox.diameterpay.com/v1/end-users/individuals \
  --header 'Authorization: Bearer {access_token}' \
  --header 'x-idempotency-key: 550e8400-e29b-41d4-a716-446655440000' \
  --header 'Content-Type: application/json' \
  --data '{
    "productId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "firstName": "Jane",
    "lastName": "Smith",
    "email": "jane.smith@example.com",
    "mobilePhone": "+12125551234",
    "dateOfBirth": "1990-07-15",
    "nationality": "US",
    "idType": "PASSPORT",
    "idNumber": "A12345678",
    "idCountry": "US",
    "pepStatus": "NO",
    "primaryAddress": {
      "addressType": "RESIDENTIAL",
      "country": "US",
      "postalCode": "10001",
      "townName": "New York",
      "streetName": "5th Avenue",
      "buildingNumber": "350",
      "countrySubdivision": "NY"
    },
    "onboardInBanks": ["PORTAGE"]
  }'
```

## Example Response

```json theme={null}
{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "productId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "firstName": "Jane",
  "middleName": null,
  "lastName": "Smith",
  "fullName": "Jane Smith",
  "email": "jane.smith@example.com",
  "mobilePhone": "+12125551234",
  "dateOfBirth": "1990-07-15",
  "nationality": "US",
  "idType": "PASSPORT",
  "idNumber": "A12345678",
  "idCountry": "US",
  "pepStatus": "NO",
  "gender": null,
  "onboardingStatus": "INACTIVE",
  "onboardedInBanks": [],
  "addresses": [
    {
      "addressType": "RESIDENTIAL",
      "country": "US",
      "postalCode": "10001",
      "townName": "New York",
      "streetName": "5th Avenue",
      "buildingNumber": "350",
      "countrySubdivision": "NY"
    }
  ],
  "internalEndUserIdentifier": null,
  "internalEndUserActivity": null,
  "internalEndUserStartDate": null,
  "createdAt": "2024-06-01T12:00:00.000Z",
  "updatedAt": "2024-06-01T12:00:00.000Z"
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.