---
title: "Create an application"
method: POST
path: "/v2/applications"
tags: ["Applications"]
---

# Create an application

`POST /v2/applications`

## Request

- Base URL: `https://api.getpaid.io`
- URL: `https://api.getpaid.io/v2/applications`
- Auth: OAuth 2
  - Client credentials
  - Token URL: `https://auth.getpaid.io/oauth/token` scopes: `accounts:read_write`
- TypeScript: <https://skmtc.dev/getpaid/apis/getpaid-api/docs/v2/applications/post.ts> (a function with typed inputs; its response is checked against the schema)

Create an application initiated by the platform so the seller can start submitting their information. It can be:

- `onboarding`: to create a new account for the seller and start accepting payments.
- `change_request`: to update an existing seller account with new information.

Related webhooks:

- [`application_submitted`](#tag/Onboard-sellers-webhooks/operation/application_submitted): sent when an application is submitted by a seller for review.
- [`application_completed`](#tag/Onboard-sellers-webhooks/operation/application_completed): sent when the application is approved and completed.
- [`application_expired`](#tag/Onboard-sellers-webhooks/operation/application_expired): sent when an application expires before it is submitted.

## Headers

- `Getpaid-Idempotency-Key` string, required

## Request body

- union
  - OnboardingApplicationRequest
    - `type` 'onboarding' | 'change_request', required: The type of application to create: - `onboarding`: to create a new account for the seller and start accepting payments. - `change_request`: to update an existing seller account with new information.
    - `reference` string, required: An identifier in your system. It is recommended to make it unique but the uniqueness is not enforced by the solution.
    - `applicant` ApplicantRequest, required: The details of the person representing the seller that is applying for the Getpaid account if known at the time of application creation.
      - `email` string, email, required: The applicant's email address.
      - `first_name` string: The applicant's first name.
      - `last_name` string: The applicant's last name.
    - `business` BusinessRequest, required: The seller business details if known at the time of application creation.
      - `legal_name` string, required: The legal name of the business.
      - `country` string, country, required: The two-letter [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).
      - `legal_structure` 'ca_private_corp' | 'ca_public_corp' | 'ca_non_profit': The legal structure of the business. **It is required to provide the legal structure of the business if the country of registration is Canada (CA).**
      - `registered_address` object: The registered address of the business.
        - `line1` string, required: The first line of the address.
        - `line2` string: The second line of the address.
        - `street_number` string, required: The number assigned to the building on the street. May include alphanumeric formatting such as "7A" or "12-14". street number.
        - `city` string, required: The city, town, municipality, or locality where the address is located.
        - `region` string: The administrative area such as region, province, state, or county.
        - `postal_code` string, required: The postal code, postcode, or ZIP code used for mail delivery.
      - `registration_number` union: The business' registration number. The registration number is validated based on the country of the business.
        - BaseRegistrationNumber: The company registration number.
          - `type` string, required: The type of registration number. See the list of supported [registration numbers per country](/integration/api/references/registration-numbers).
          - `value` string, required: The registration number. See the format for each registration number type in the [registration numbers list](/integration/api/references/registration-numbers).
        - GermanRegistrationNumber: The company registration number.
          - `type` string, required: The type of registration number. See the list of supported [registration numbers per country](/integration/api/references/registration-numbers).
          - `value` string, required: The registration number. See the format for each registration number type in the [registration numbers list](/integration/api/references/registration-numbers).
          - `registry` string, required: The Germany district court where the business is registered. See the [list of Germany registry courts](/integration/api/references/registration-numbers/germany-registry-courts).
    - `redirect` object, required: Configuration for the redirect behavior after the onboarding application is submitted.
      - `default` string, uri, required: The URL to which the seller will be redirected after the onboarding application is submitted.
    - `expires_in` string, time-span: Duration in `[d.]hh:mm[:ss]` notation. Days and seconds optional, all segments non-negative. Hours above 23 are supported but not recommended. Excess hours roll over into the days component; for example, 1.720:00 represents 31 days.
    - `webhooks` ApplicationWebhooksRequest: Configuration for webhooks to receive onboarding application status updates.
      - `url` string, uri, required: The URL to which webhook events will be sent.
  - ChangeRequestApplicationRequest
    - `type` 'onboarding' | 'change_request', required: The type of application to create: - `onboarding`: to create a new account for the seller and start accepting payments. - `change_request`: to update an existing seller account with new information.
    - `account` object, required: The seller account whose information is being updated by this change request.
      - `id` string, id, required: The unique identifier of the account.
    - `reference` string, required: An identifier in your system. It is recommended to make it unique but the uniqueness is not enforced by the solution.
    - `fields` ApplicationFieldRequest[], required: The list of fields whose access is granted to the seller while the change request application is open. The application is scoped to these fields only — the seller can review and update them, and any other field remains unchanged.
      - `name` 'themes', required: The name of the field whose access is controlled by the application.
      - `access` 'read_write', required: The level of access granted to the seller over the field while the application is open.
    - `redirect` object: Configuration for the redirect behavior after the change request application is submitted.
      - `default` string, uri, required: The URL to which the seller will be redirected after the change request application is submitted.
    - `theme_id` string, id: The ID of the platform theme used to brand the hosted change request page. This affects only the appearance of the page itself and does not change the seller account's theme settings. If not provided, the account's default theme is used.
    - `expires_in` string, time-span: Duration in `[d.]hh:mm[:ss]` notation. Days and seconds optional, all segments non-negative. Hours above 23 are supported but not recommended. Excess hours roll over into the days component; for example, 1.720:00 represents 31 days.
    - `webhooks` ApplicationWebhooksRequest: Configuration for webhooks to receive onboarding application status updates.
      - `url` string, uri, required: The URL to which webhook events will be sent.

## Response `201`

Created

- CreateApplicationResponse
  - `id` string, id, required: The unique identifier of the onboarding application.
  - `status` 'initiated' | 'identity_verified' | 'submitted' | 'screened' | 'approved' | 'completed' | 'cancelled' | 'expired', required: The status of the onboarding application.
  - `reference` string, required: An identifier in your system. It is recommended to make it unique but the uniqueness is not enforced by the solution.
  - `created_at` string, date-time, required: UTC timestamp in ISO 8601 format with milliseconds ([RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html)). Always includes the 'Z' UTC indicator.
  - `updated_at` string, date-time, required: UTC timestamp in ISO 8601 format with milliseconds ([RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html)). Always includes the 'Z' UTC indicator.
  - `expires_at` string, date-time, required: UTC timestamp in ISO 8601 format with milliseconds ([RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html)). Always includes the 'Z' UTC indicator.
  - `account` object, required: The account associated with the application, if created.
    - `id` string, id, required: The unique identifier of the account.
  - `flow` ApplicationFlow, required: The flow required for the onboarding application to complete.
    - `next_step` object, required: The next step required to complete the flow.
      - `type` 'redirect', required: The type of the next step.
      - `url` string, uri, required: The URL to redirect the seller to complete the onboarding.
      - `expires_at` string, date-time: UTC timestamp in ISO 8601 format with milliseconds ([RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html)). Always includes the 'Z' UTC indicator.

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `422`: Invalid Parameters
- `429`: Too Many Requests
- `500`: Internal Server Error

---

[API](https://skmtc.dev/getpaid/apis/getpaid-api.md) - [All operations](https://skmtc.dev/getpaid/apis/getpaid-api/llms.txt) - [OpenAPI document](https://skmtc.dev/getpaid/apis/getpaid-api/revisions/458eae3d49ad?raw)