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

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.

Show 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

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

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