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. [phone]).

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.

Show 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.

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

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": "[e-mail]",
    "mobilePhone": "[phone]",
    "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

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "productId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "firstName": "Jane",
  "middleName": null,
  "lastName": "Smith",
  "fullName": "Jane Smith",
  "email": "[e-mail]",
  "mobilePhone": "[phone]",
  "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"
}