> ## 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 Organization End User

> POST /v1/end-users/organizations — Creates a new organization (business) end user and initiates bank onboarding. Requires end-users.write scope.

Creating an organization end user registers a business entity on the Diameter platform and immediately kicks off the bank onboarding process for each bank partner you specify. This endpoint accepts business identity details, registered address information, and compliance data. Once asynchronous onboarding completes for a given bank, it appears in the `onboardedInBanks` array and accounts can be created under that organization.

## Endpoint

```
POST /v1/end-users/organizations
```

**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 organization.

## Request Body

### Required Fields

**productId** `string` *required*

UUID v4 of the Diameter product to associate with this organization.

**fullName** `string` *required*

Full legal registered name of the organization.

**doingBusinessAs** `string` *required*

Trade name or DBA ("doing business as") name the organization operates under.

**businessIndustry** `string` *required*

Industry description, ideally including the NAICS code (e.g. `"Automobile Manufacturing (NAICS 336111)"`).

**businessEntityType** `string` *required*

Legal entity classification. One of: `CORPORATION`, `LLC`, `GENERAL_PARTNERSHIP`, `LIMITED_LIABILITY_PARTNERSHIP`, `LIMITED_LIABILITY_COMPANY`, `NON_PROFIT`, `PUBLICLY_TRADED_COMPANY`, `GOVERNMENT_ORGANIZATION`, `SOLE_PROPRIETOR`.

**formationDate** `string` *required*

Date the organization was legally formed, in `YYYY-MM-DD` format.

**incorporationCountry** `string` *required*

ISO 3166-1 alpha-2 country code where the organization is incorporated.

**idType** `string` *required*

Type of business identification document. One of: `EIN`, `SSN`, `TIN`, `OTHER_ID`, `DRIVING_LICENSE`, `NATIONAL_ID_CARD`.

**idNumber** `string` *required*

The identifier number for the chosen business ID type.

**email** `string` *required*

Primary contact email address for the organization.

**mobilePhone** `string` *required*

Primary contact phone number in E.164 format (e.g. `+12125559876`).

**pepStatus** `string` *required*

Politically Exposed Person status for the organization's beneficial owners. One of: `YES`, `NO`.

**primaryAddress** `object` *required*

The organization's primary registered address.

**primaryAddress fields**

**addressType** `string` *required*

Address type label (e.g. `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 suite number.

**countrySubdivision** `string`

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

**district** `string`

District or borough.

**floor** `string`

Floor number within the building.

**room** `string`

Room or suite identifier.

**department** `string`

Department name.

**subDepartment** `string`

Sub-department name.

**postOfficeBox** `string`

PO Box identifier.

**onboardInBanks** `array` *required*

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

### Optional Fields

**incorporationState** `string`

State or province of incorporation (e.g. `DE` for Delaware). Relevant for US-based entities.

**website** `string`

Organization's website. Accepts a full URL (e.g. `https://example.com`) or a bare domain (e.g. `example.com`).

**mailingAddress** `object`

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

**internalEndUserIdentifier** `string`

Your system's internal identifier for this organization. Maximum 255 characters.

**internalEndUserActivity** `integer`

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

**internalEndUserStartDate** `string`

Date this organization became active in your system (`YYYY-MM-DD`).

## Response

Returns `201 Created` with the newly created organization end user object.

**id** `string`

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

**productId** `string`

UUID of the associated product.

**fullName** `string`

Full legal name of the organization.

**doingBusinessAs** `string`

DBA or trade name.

**businessIndustry** `string`

Industry description as submitted.

**businessEntityType** `string`

Legal entity type.

**formationDate** `string`

Formation date in `YYYY-MM-DD` format.

**incorporationCountry** `string`

ISO 3166-1 alpha-2 country code of incorporation.

**incorporationState** `string`

State of incorporation, if provided.

**idType** `string`

Business identification document type.

**idNumber** `string`

Business identification number.

**email** `string`

Organization's contact email.

**mobilePhone** `string`

Organization's contact phone in E.164 format.

**pepStatus** `string`

PEP status: `YES` or `NO`.

**website** `string`

Organization's website, if provided.

**onboardingStatus** `string`

Overall onboarding status. Starts as `INACTIVE`; 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 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 organization 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/organizations \
  --header 'Authorization: Bearer {access_token}' \
  --header 'x-idempotency-key: 7c9e6679-7425-40de-944b-e07fc1f90ae7' \
  --header 'Content-Type: application/json' \
  --data '{
    "productId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "fullName": "Acme Technologies Inc.",
    "doingBusinessAs": "Acme Tech",
    "businessIndustry": "Computer Systems Design (NAICS 541512)",
    "businessEntityType": "CORPORATION",
    "formationDate": "2010-03-22",
    "incorporationCountry": "US",
    "incorporationState": "DE",
    "idType": "EIN",
    "idNumber": "12-3456789",
    "email": "finance@acmetech.com",
    "mobilePhone": "+12125559876",
    "pepStatus": "NO",
    "website": "https://acmetech.com",
    "primaryAddress": {
      "addressType": "BUSINESS",
      "country": "US",
      "postalCode": "19801",
      "townName": "Wilmington",
      "streetName": "Market Street",
      "buildingNumber": "100",
      "countrySubdivision": "DE"
    },
    "onboardInBanks": ["PORTAGE"]
  }'
```

## Example Response

```json theme={null}
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "productId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "fullName": "Acme Technologies Inc.",
  "doingBusinessAs": "Acme Tech",
  "businessIndustry": "Computer Systems Design (NAICS 541512)",
  "businessEntityType": "CORPORATION",
  "formationDate": "2010-03-22",
  "incorporationCountry": "US",
  "incorporationState": "DE",
  "idType": "EIN",
  "idNumber": "12-3456789",
  "email": "finance@acmetech.com",
  "mobilePhone": "+12125559876",
  "pepStatus": "NO",
  "website": "https://acmetech.com",
  "onboardingStatus": "INACTIVE",
  "onboardedInBanks": [],
  "addresses": [
    {
      "addressType": "BUSINESS",
      "country": "US",
      "postalCode": "19801",
      "townName": "Wilmington",
      "streetName": "Market Street",
      "buildingNumber": "100",
      "countrySubdivision": "DE"
    }
  ],
  "internalEndUserIdentifier": null,
  "internalEndUserActivity": null,
  "internalEndUserStartDate": null,
  "createdAt": "2024-06-01T14:30:00.000Z",
  "updatedAt": "2024-06-01T14:30:00.000Z"
}
```


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