---
title: "Create account application"
method: POST
path: "/acquisitions/v3/s2s/applications"
tags: ["Accounts"]
---

# Create account application

`POST /acquisitions/v3/s2s/applications`

## Request

- Base URL: `https://sandbox.pismolabs.io`
- URL: `https://sandbox.pismolabs.io/acquisitions/v3/s2s/applications`
- Auth: HTTP bearer

Create a new account application.

If `submit` is set to `false`:

- The application is not sent for processing and can be further modified  with incremental changes via [Update account application](ref:patch-acquisitions-v2-s2s-applications).

- This endpoint generates an [Account application prospect created](https://developers.pismo.io/events/docs/onboarding-prospect-1) event.

If `submit` flag is set to `true`:

- No further updates can be made and the account application is sent out for processing, which creates an account and its associated structures.

- This endpoint generates an [Account application created](https://developers.pismo.io/events/docs/onboarding-succeeded-1) event.


**Warning**—Some of the account's elements are created asynchronously and you should refrain from accessing the account via other endpoints until the events this endpoint generates are received.

**Notes:**
  * Either the `personal` object or `company` object is **REQUIRED**. Pass one or the other but not both.
  * This endpoint creates a default `entity` object for the account owner based on document ID.

Refer to the [Core objects](doc:setup-overview) and the [Accounts](doc:accounts-overview) guides for more information.

## Request body

- object
  - `application` AcquisitionRequestV3, required: Application form
    - `submit` boolean, required: Should form be processed now (`true`), or later after adding more information (`false`).
    - `applicant` Applicant, required: Applicant's details
      - `document_number` string, required: Applicant's document number (such as a government tax ID). For a company, this can be something like its tax or business registration number. **Important**: Once passed, this value **CANNOT** be changed, even if `submit` is `false`.
      - `birth_date` string, date: Birth date. Format = yyyy-mm-dd. For a company, this can be the company creation date.
      - `personal` ApplicantPersonal: Applicant's personal information. Either this or the `company` object is **REQUIRED**. Pass one or the other but not both.
        - `external_id` string: Client-supplied personal ID from an external system or application.
        - `name` string: Name. **REQUIRED** if `social_name` is not provided.
        - `email` string, email: Email address.
        - `gender` 'F' | 'M' | '': Gender
        - `printed_name` string: This field is **DEPRECATED**. Cards is now responsible for this field. Name to be printed on the card. **REQUIRED** if `name` and `social_name` are not provided. Punctuation, special characters, and connectors (da/das/de/do/dos/e) are always removed. This field's maximum length is 25, but you can set it to a lower value at the program level with the `Max name length on physical card` program parameter.
        - `nickname` string: Nickname.
        - `social_name` string: Social name. **REQUIRED** if `name` is not provided.
        - `country_of_birth` string: Birth country
        - `state_of_birth` string: Birth state
        - `city_of_birth` string: Birth city
        - `registration` ApplicantRegistration: Applicant's document information
          - `number` string: Document number, such as a tax ID.
        - `education_degree` string: Education degree
        - `marital_status` 'SINGLE' | 'MARRIED' | 'DIVORCED' | 'WIDOWER': Marital status
        - `fathers_name` string: Father's name
        - `mothers_name` string: Mother's name
        - `nationality` string: Nationality
        - `other_id_number` string: Another ID number
        - `document_type` string: Document type. Free-form field, not an enum.
        - `document_issued_by` string: Document issuer
        - `document_issued_at` string: Document issuer location. This is a free-form field, not an ISO standard.
        - `document_issued_date` string: Date document was issued. Format = dd/mm/yyyy.
        - `occupation` string: Applicant's occupation
        - `assets` number, float: Assets
        - `income` integer: Applicant's income
        - `net_worth` integer: Applicant's net worth
        - `pep` boolean: Is this person a Politically Exposed Person (PEP)? Pismo doesn't do anything differently for a PEP, this is just additional account information. Default is `false`.
        - `statutory` boolean: Is person statutory? A statutory employee is defined as an employee by law under a specific statute. Pismo doesn't do anything differently in this case, it is simply additional account information. Default is `false`.
      - `company` ApplicantCompany: Applicant's company information. Either this or the `personal` object is **REQUIRED**. Pass one or the other but not both.
        - `external_id` string: Client-provided company ID from an external system.
        - `name` string, required: Company's legal name
        - `email` string: Company's registered email
        - `company_name` string: Company's brand name
        - `registration_number` string: Company's registration number with local authorities
        - `activity` string: Company's general field of activity
        - `company_type` string: Company type
        - `company_format` string: Company social type
        - `company_constitution_date` string, date: Company's operational start date. Format = yyyy-mm-dd.
        - `occupation` string: Company's main occupation
        - `income` integer: Company's income
        - `net_worth` integer: Company's net worth
        - `annual_revenues` integer: Average monthly revenue for the last 12 months
        - `type` string: Company's business relations type
        - `number_of_partners` integer: Number of company partners
        - `perc_ownership` integer: Company percentage ownership
        - `fiscal_situation` string: Company's fiscal situation.
        - `debt` integer: Company's debt
        - `partners` Partner[]: Company partners
          - `name` string: Name - person or company name
          - `nickname` string: Nickname.
          - `printed_name` string: This field is **DEPRECATED**. Name to be printed on the card. Punctuation, special characters, and connectors (da/das/de/do/dos/e) are always removed. This field's maximum length is 25, but you can set it to a lower value at the program level with the `Max name length on physical card` program parameter. If `printed_name` is null, the Pismo platform uses `social_name`. If `social_name` is null, the Pismo platform uses the customer's entity name. For more information on the customer object, refer to [Core objects](doc:setup-overview#customer). The Pismo platform gets the name for program parameter `TAMANHO MAX NOME EMBOSSADO` (max size name embossed).
          - `social_name` string: Social name.
          - `email` string, email: Email address.
          - `document_number` string: Document number, such as a government tax ID.
          - `mothers_name` string: Mother's name
          - `gender` 'F' | 'M' | '': Gender
          - `birth_date` string: Birth date. Format = dd/mm/yyyy.
          - `city_of_birth` string: Birth city
          - `state_of_birth` string: Birth state
          - `country_of_birth` string: Birth country
          - `fathers_name` string: Father's name
          - `marital_status` 'SINGLE' | 'MARRIED' | 'DIVORCED' | 'WIDOWER': Marital status
      - `account` ApplicantAccount: Applicant's account options
        - `currency_numeric_code` string: ISO 4217 code for account's currency. If not defined, the Pismo platform uses the program currency code. If not defined at the program level, the platform uses the currency code defined at the organization level.
        - `granted_limit` number, float: Account's credit limit. **REQUIRED** for credit programs. This field is called `max_credit_limit` in the [Update account limits](https://developers.pismo.io/pismo-docs/reference/patch-v1-account-limit) endpoint and the [Account limits](https://developers.pismo.io/pismo-docs/docs/working-with-limits-objects) guide.
        - `limit` number, float: Client-defined account limit. Must be between 0 and the `granted_limit` (aka `max_credit_limit`). Defaults to zero (0) if not passed. This field is called `total_credit_limit` in the [Update account limits](https://developers.pismo.io/pismo-docs/reference/patch-v1-account-limit) endpoint and the [Account limits](https://developers.pismo.io/pismo-docs/docs/working-with-limits-objects) guide.
        - `exchange_mode` 'SAME_DAY' | 'CLOSING': When a foreign transaction is charged the exchange rate: * `SAME_DAY` - Day the transaction occurred * `CLOSING` - Statement's closing date This field is valid for credit [programs](doc:program-types) **only**.
        - `external_id` string: Client-created ID from an external system or application. **REQUIRED** for `VIRTUAL` accounts.
        - `parent_account_id` integer: Parent account ID. **REQUIRED** for `VIRTUAL` accounts.
        - `overdraft_limit` number, float: Maximum issuer-granted limit for overdraft spending on debit accounts
        - `account_type` 'PHYSICAL' | 'VIRTUAL': Account type: - `PHYSICAL`—Default. A parent account is always physical. A child account can be physical or virtual. A *physical* card is a plastic or metal embossed card. "Physical" here means an account that represents an actual client entity (person or company). A physical account supports full operations— transfers, payments, cards, interest, statements, and so on. - `VIRTUAL`—Always a child account. `parent_account_id` and `external_id` are **REQUIRED** for virtual accounts. Virtual accounts can have a many to one mapping to a physical account where the balance lives at the parent account. While a `document_number` is **REQUIRED** for a virtual account, it is ignored since it shares a parent account's entity and `document_number`. **Key difference summary** | Feature | Physical | Virtual | | ------------------------------ | ------------------ | -------------------------- | | Fund ownership | Yes | No (parent owns funds) | | Independent balance | Usually | Typically parent balance | | Persistent ID | One account | Can be many to one parent | | Regulatory/KYC link | Direct | Inherited/indirect | | Primary use | Real account | Segmentation & routing |
        - `division_id` integer: Account's administrative division ID
        - `centralizer` boolean: Is this a centralizer account? A centralizer account, within the account hierarchy, is the account responsible for invoice billing. Defaults to `false`.
      - `addresses` object[]: List of addresses
        - `address` string, required: Street, avenue, road, and so on, name.
        - `number` string: Address number as string or integer. If you enter numeric characters, they are saved in the `number` address object field. If you enter any non-numeric characters, all characters are saved in the `extended_number` address object field. For example, if you enter "12 A", it gets saved as follows: * `number` = 12 * `extended_number` = "12 A"
        - `city` string, required: Address city
        - `state` string, required: Address state
        - `country` string, required: Address country
        - `address_type` 'RESIDENTIAL' | 'COMMERCIAL' | 'OTHER', required: Address type
        - `zip_code` string, required: Zip/postal code
        - `neighborhood` string, required: Address neighborhood. Some countries use neighborhood in addresses.
        - `complementary_address` string: Any additional information such as suite, apt., and so on.
        - `mailing_address` boolean: Is this address the mailing address? Only one address can have this field set to `true`.
        - `custom_fields` CustomFields: Key/value field for custom information. (Limited to 1014 bytes.)
      - `phones` object[]: List of phone numbers
        - `phone` string, required: Phone number
        - `phone_type` 'RESIDENTIAL' | 'COMMERCIAL' | 'MOBILE', required: Phone number type
        - `country_code` string, required: Phone number's country code
        - `area_code` integer: Phone number area code
        - `extension` string: Optional phone number extension
      - `custom_fields` CustomFields: Key/value field for custom information. (Limited to 1014 bytes.)
    - `acquisition_channel` integer: Application's acquisition channel ID. An acquisition channel is how a customer was referred to the site, such as through a web app or mobile app. You can call [List acquistion channels](ref:get-acquisitions-v2-programs-programid-channels) to find channels registered for your account.
    - `program_id` integer: Program ID. **REQUIRED** when `acquisition_channel` is not passed.
    - `due_date` integer: Program due date ID. This field is **REQUIRED** only for Full balance credit programs. Program due dates and their IDs are set when you [create a program](ref:createprogrambasedontemplate).
    - `program_calendar_strategy_id` number: Program calendar strategy ID. The program calendar strategy determines how program calendars are created. For more information, refer to the [Create program calendar strategy](ref:createprogramcalendarstrategy) endpoint. This endpoint returns an ID you can pass here.

## Response `201`

Created

- AcquisitionResponseV3: Aquisition form was successfully created.
  - `application_id` integer, required: Application form ID (non-checking accounts only)
  - `status` integer, required: Application status ID
  - `status_name` string, required: Application status. Most likely to be * `REGISTERED` - Application was saved, but not started processing yet. * `APPROVED` - Application has finished processing. * `PROSPECT` - Application was created with `submit` = `false`.
  - `account_id` integer, required: Created account ID. `null` if the application has not been proccessed yet (non-checking accounts only).
  - `customer_id` integer, required: Created customer ID. `null` if the application has not yet been proccessed (non-checking accounts only).
  - `entity_id` integer, required: Created entity ID. `null` if the application has not yet been proccessed (non-checking accounts only).
  - `program_id` integer, required: Program ID
  - `creation_datetime` string, date-time: Date and time of account creation in the UTC ISO 8601 format (yyyy-MM-ddThh:mm:ssZ).

## Other responses

- `400`: Bad request
- `409`: Conflict
- `500`: Internal server error

---

[API](https://skmtc.dev/pismo/apis/core-platform-accounts.md) - [All operations](https://skmtc.dev/pismo/apis/core-platform-accounts/llms.txt) - [OpenAPI document](https://skmtc.dev/pismo/apis/core-platform-accounts/revisions/0b24a835073b?raw)