---
title: "Create Link Token"
method: POST
path: "/link_tokens"
tags: ["Link Tokens"]
---

# Create Link Token

`POST /link_tokens`

Create a token used to launch a Link modal.

## Headers

- `Pinwheel-Version` '2025-07-08' | '2023-11-22' | '2023-07-18' | '2023-04-18' | '2022-09-09' | '2022-06-22' | '2022-03-02', required

## Request body

- LinkTokenCreateV20250708
  - `org_name` string, required — Organization or app name that is displayed to the user.
  - `allocation` Allocation
    - `type` 'amount' — Type of allocation.
    - `value` union — Value of allocation. If type is amount, you must include a value. If type is null, the end-user will be able to select the allocation type and value. If min_amount is also specified for the allocation, must be greater than or equal to min_amount.
      - number
      - string
    - `min_amount` union — Minimum amount for the allocation.
      - number
      - string
    - `targets` BankAccountDetails[] — List of allowed target accounts for an allocation.
      - `name` string — Name of the bank account.
      - `type` 'checking' | 'savings' — Bank account type, checking or savings. Required if requesting direct_deposit_switch jobs.
      - `routing_number` string — Routing number of bank. Required if requesting direct_deposit_switch jobs.
      - `account_number` string — Bank account number. Required if requesting direct_deposit_switch jobs.
  - `skip_intro_screen` boolean — If set to true, intro screen is not shown to user.
  - `employer_id` string, uuid — UUID of an employer. If set, user is taken directly to Link login screen.
  - `disable_direct_deposit_splitting` boolean — If set to true, user will not be given the option to choose between a full or partial direct deposit switch. Only relevant with job `direct_deposit_switch`. Defaults to false.
  - `platform_id` string, uuid — UUID of a platform. If set, user is taken directly to Link login screen.
  - `platform_type` 'payroll' | 'time_and_attendance' | 'tax' | 'merchant' — The type of the platform. `payroll` platforms are used for direct-deposit switching and for Verify use cases. `time_and_attendance` platforms contain data around shifts and hours. `tax` platforms are used for tax solutions. `merchant` type platforms are used for bill switching and cancellation.
  - `language` 'en' | 'es' | 'es-419' | 'pt-br' — IETF code denoting which language to display in Link.
  - `end_user_id` string — User ID provided by you, to associate Pinwheel users with your user model. Required if `account_id` is not provided. This ID will be returned in all webhook events and all account-affiliated API responses. Leading and trailing whitespace will be stripped. Do not include PII in this identifier.
  - `account_id` string, uuid — UUID of the payroll account.
  - `document_uploads` 'direct' | 'fallback' | 'disabled' — Optional parameter to facilitate pathway into document uploads usage. Defaults to None.
  - `tags` object — Tags associated with the Link token. These are restricted to string key-value pairs.
  - `deposit_forms` 'direct' | 'fallback' | 'disabled' — Optional parameter to facilitate pathway into deposit forms. Defaults to fallback if deposit forms are enabled for your workspace.
  - `use_case` 'account_onboarding' | 'account_servicing' | 'underwriting' — Field to indicate where in your application Pinwheel is being launched. Required if leveraging Background Identify (PreMatch employee lookup check prior to SDK initialization).
  - `end_user` EndUser
    - `platform_matching` LinkUserAuthenticationDataObjCreate
      - `social_security_number` string — Full 9-digit social security number of the user (required). Using full SSN will improve conversion.
      - `social_security_number_last_four` string — Last four digits of the user's social security number. Use this field only when the full 9-digit SSN (social_security_number) is not available. Passing the full SSN yields over 20% higher match rate compared to using only the last four digits.
      - `date_of_birth` string — The user's date of birth in `YYYY-MM-DD` format (required).
      - `last_name` string — The user's last name (required).
      - `first_name` string — The user's first name (required).
      - `mobile_phone_number` string — The users's 10-digit mobile phone number (required). Do not include country code.
      - `home_address_zip_code` string — The user's 5-digit home zip code (required).
      - `email` string, email — The user's email (strongly recommended). The email must have valid syntax with an @ and valid domain e.g. `name@example.com`. If provided email is invalid a 400 will be returned. For more details on validation see https://github.com/JoshData/python-email-validator.
  - `cards` CardDetails[] — Card details needed to attempt a bill switch.
    - `card_name` string, required — Name of the card. Required if requesting `bill_switch` job.
    - `card_number` string, required — Card number. Required if requesting `bill_switch` job.
    - `cvc` string — Card verification code or other security code of the card. Required if requesting `bill_switch` job.
    - `expiration_date` string, required — Expiration date of the card in MM/YY format. Required if requesting `bill_switch` job.
    - `name_on_card` string, required — Full name displayed on the card. Required if requesting `bill_switch` job.
    - `card_zip_code` string, required — Zip code for the card. Required if requesting `bill_switch` job.
    - `billing_address` string — Billing address line one of the card. Required if requesting `bill_switch` job.
    - `billing_address_two` string — Billing address line two of the card. Required if requesting `bill_switch` job.
    - `city` string — City of the card. Required if requesting `bill_switch` job.
    - `state` 'AL' | 'AK' | 'AZ' | 'AR' | 'CA' | 'CO' | 'CT' | 'DE' | 'DC' | 'FL' | 'GA' | 'HI' | 'ID' | 'IL' | 'IN' | 'IA' | 'KS' | 'KY' | 'LA' | 'ME' | 'MD' | 'MA' | 'MI' | 'MN' | 'MS' | 'MO' | 'MT' | 'NE' | 'NV' | 'NH' | 'NJ' | 'NM' | 'NY' | 'NC' | 'ND' | 'OH' | 'OK' | 'OR' | 'PA' | 'RI' | 'SC' | 'SD' | 'TN' | 'TX' | 'UT' | 'VT' | 'VA' | 'WA' | 'WV' | 'WI' | 'WY' — Two letter state code of the card, e.g. `NY`. Required if requesting `bill_switch` job.
  - `reseller_customer_id` string — The identifier for a reseller's customer. This field is required for resellers. For other customers, a non-null value will result in a 400 error. The value supplied must be preregistered with Pinwheel's customer success team.
  - `solution` 'Paycheck Viewer' | 'Verify' | 'Switch Kit' | 'Bill Manager' | 'Bill Switch' | 'Deposit Switch', required — The Pinwheel solution to be presented to the user.
  - `features` string[] — A list of job types to be performed on the user's account. Platforms/merchants that do not support ALL of these jobs will not be visible to the user. This property is required unless the account_id property is set.

## Response `200`

OK

- object
  - `data` LinkTokenObjResponseV20210728, required
    - `mode` 'sandbox' | 'development' | 'production', required — Token mode, i.e. `sandbox`, `development`, or `production`.
    - `id` string, uuid, required — UUID of the link token.
    - `token` string, required — Short-lived token that is used to initialize Pinwheel Link.
    - `smart_branch_url` string — URL that will initiate a Pinwheel-hosted smart branch experience, if smart branch is configured for the workspace.
    - `expires` string, date-time, required — The token will be invalid after this timestamp.

---

[API](https://skmtc.net/getpinwheel/apis/pinwheel.md) · [All operations](https://skmtc.net/getpinwheel/apis/pinwheel/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/getpinwheel/pinwheel/revisions/8ef86dd4902e/schema)