--- title: "Create an application" method: POST path: "/v2/applications" tags: ["Application"] --- # Create an application `POST /v2/applications` ## Request - Base URL: `https://api.sandbox.lead.bank` - URL: `https://api.sandbox.lead.bank/v2/applications` - Auth: HTTP bearer Report a final underwriting decision. The Application is created in its final status, `approved`, `declined`, or `canceled`, and the status cannot change afterward. Each `documents` entry references a File you uploaded with `POST /v2/files`. Lead checks that each File exists, belongs to your program, and has a [compliance document type](https://docs.lead.bank/v2/products/files/file-object#the-type-enum). Send `[]` when you have no documents yet. ## Headers - `Idempotency-Key` string, required ## Request body - CreateApplicationRequestBodyV2: Request body for `POST /v2/applications`. The application is created in its final status. `client_application_id` and `legacy_documents` are read only. Lead ignores them, and any other field this endpoint does not define, if sent. - `status` 'approved' | 'declined' | 'canceled', required: Terminal state of the application. Possible values: `approved`, `declined`, `canceled`. - `product_name` string, required: Your internal product name. It tells Lead which product the application opens a user account for if approved. Use a stable name. - `entities` CreateApplicationEntitiesV2, required: The entities on the application. Each must already exist. Each relationship type takes up to 20 entities, and no entity can appear twice in one type. The account holders must be all consumer (individuals) or all commercial (businesses or sole proprietorships). On `approved` applications only, each entity must be eligible for its relationship type, and a commercial application needs at least one authorized signer. Your program can also require credit data on each account holder's and authorized signer's entity for approved applications; your Technical Account Manager can tell you whether yours does. `account_holder_type` is derived by Lead and response only, so Lead ignores it if sent. Entities cannot change after creation. - `account_holders` EntityID[], required: Entity IDs of the applicants. At least one. - `authorized_signers` EntityID[]: Entity IDs of authorized signers. An `approved` commercial application needs at least one. - `authorized_users` EntityID[]: Entity IDs of authorized users. Lead accepts them on create but does not return them on the application. List them with `GET /v2/applications/{id}/entity_relationships`. - `details` CreateApplicationDetailsV2, required: Underwriting and adverse action notice details. - `underwriting` CreateApplicationUnderwritingV2, required: Underwriting inputs and outcomes. - `is_secured` boolean, required: `true` if collateral secures the product. - `is_mla` boolean, required: `true` if the applicant is covered by the Military Lending Act. - `currency_code` 'AED' | 'AFN' | 'ALL' | 'AMD' | 'AOA' | 'ARS' | 'AUD' | 'AWG' | 'AZN' | 'BAM' | 'BBD' | 'BDT' | 'BGN' | 'BHD' | 'BIF' | 'BMD' | 'BND' | 'BOB' | 'BRL' | 'BSD' | 'BTN' | 'BWP' | 'BYN' | 'BZD' | 'CAD' | 'CDF' | 'CHF' | 'CLP' | 'CNH' | 'CNY' | 'COP' | 'CRC' | 'CUC' | 'CUP' | 'CVE' | 'CZK' | 'DJF' | 'DKK' | 'DOP' | 'DZD' | 'EGP' | 'ERN' | 'ETB' | 'EUR' | 'FJD' | 'FKP' | 'GBP' | 'GEL' | 'GGP' | 'GHS' | 'GIP' | 'GMD' | 'GNF' | 'GTQ' | 'GYD' | 'HKD' | 'HNL' | 'HTG' | 'HUF' | 'IDR' | 'ILS' | 'IMP' | 'INR' | 'IQD' | 'IRR' | 'ISK' | 'JEP' | 'JMD' | 'JOD' | 'JPY' | 'KES' | 'KGS' | 'KHR' | 'KMF' | 'KPW' | 'KRW' | 'KWD' | 'KYD' | 'KZT' | 'LAK' | 'LBP' | 'LKR' | 'LRD' | 'LSL' | 'LYD' | 'MAD' | 'MDL' | 'MGA' | 'MKD' | 'MMK' | 'MNT' | 'MOP' | 'MRU' | 'MUR' | 'MVR' | 'MWK' | 'MXN' | 'MYR' | 'MZN' | 'NAD' | 'NGN' | 'NIO' | 'NOK' | 'NPR' | 'NZD' | 'OMR' | 'PAB' | 'PEN' | 'PGK' | 'PHP' | 'PKR' | 'PLN' | 'PYG' | 'QAR' | 'RON' | 'RSD' | 'RUB' | 'RWF' | 'SAR' | 'SBD' | 'SCR' | 'SDG' | 'SEK' | 'SGD' | 'SHP' | 'SLE' | 'SOS' | 'SRD' | 'SSP' | 'STD' | 'STN' | 'SVC' | 'SYP' | 'SZL' | 'THB' | 'TJS' | 'TMT' | 'TND' | 'TOP' | 'TRY' | 'TTD' | 'TWD' | 'TZS' | 'UAH' | 'UGX' | 'USD' | 'UYU' | 'UYW' | 'UZS' | 'VES' | 'VND' | 'VUV' | 'WST' | 'XAF' | 'XCD' | 'XCG' | 'XMW' | 'XOF' | 'XPF' | 'YER' | 'ZAR' | 'ZMW' | 'ZWG', required: A three-letter currency code as defined in ISO 4217 - `underwriting_grade` string: Your internal underwriting grade. Any string. Required when `status` is `approved` or `declined`. - `limit` integer: The credit limit assigned, in minor units. Required when `status` is `approved`. Cannot exceed `max_limit`. - `max_limit` integer: The highest limit the applicant was approved for in original underwriting, in minor units. Required when `status` is `approved`. - `report` CreditReportV2: Credit bureau data. Optional unless your program requires it. When you send a report, `pulled_at` and `source` are required, and you send exactly one of `score` or `non_score_value`. - `score` integer: The bureau score, from 300 to 850. Cannot be sent with `non_score_value`. - `non_score_value` 'unestablished' | 'frozen': Sent when the bureau returned no numeric score. Cannot be sent with `score`. - `pulled_at` string, date-time, required: When you pulled the report. - `source` 'equifax' | 'experian' | 'transunion', required: The credit bureau. - `adverse_action_notice` AdverseActionNoticeV2: The adverse action notice you sent the applicant. Required when `status` is `declined`. All three fields are required when the object is present. - `delivered_at` string, date-time, required: When you sent the notice to the applicant. - `reason` string, required: The reason stated in the notice. - `delivery_method` 'email' | 'text' | 'other', required: How you delivered the notice. - `decision` DecisionV2, required: When and why the underwriting decision was made. - `decided_at` string, date-time, required: When you made the underwriting decision. - `reason` string, required: The reason for the decision. - `exception_approval_reason` string: Send only when the decision was an exception to your underwriting criteria. The reason for approving outside your standard process. - `documents` FileDocument[], required: Legal or informational documents associated with the application, each referencing a file you uploaded with `POST /v2/files`. Lead accepts only files whose type can link to an application. See the [file type enum list](https://docs.lead.bank/v2/products/files/file-object#the-type-enum). A supplied array replaces the whole array, and Lead re-checks every `file_id` in it. Send `[]` when you have no documents to link yet. - `file_id` string, required: Lead-issued identifier of the file, from `POST /v2/files`. - `timestamp` string, date-time, required: When the end-user was shown or agreed to the document, per the file type. Partner-supplied; records an exchange between the partner and end-user, never upload time. ISO 8601, UTC. - `version` string: Partner-supplied label used for static documents so that two entries of the same type on one object can be ordered (e.g. terms of use v1 and v2). - `metadata` object: Key-value pairs for your own use. ## Response `200` Application created. - ApplicationV2: An application, your report of an underwriting decision. Applications created on v0 are returned in this shape. - `id` string, required: Unique identifier for the application. Prefixed with `application_`. - `client_application_id` string: Your ID for applications you reported in an Application file. Lead omits it for applications created through the API. - `status` 'approved' | 'declined' | 'canceled' | 'submitted' | 'under_review', required: The application's status. Applications created through the API are always `approved`, `declined`, or `canceled`, the statuses `POST` accepts. `submitted` and `under_review` appear only on applications you reported in an Application file before a decision was made. They are read only: `POST` does not accept them, and a `PATCH` that includes `status` leaves it unchanged. - `product_name` string, required: Your internal product name. - `entities` ApplicationEntitiesV2, required: The entities on the application. Authorized users are not returned here; list them with `GET /v2/applications/{id}/entity_relationships`. - `account_holder_type` 'consumer' | 'commercial': Derived by Lead. `consumer` if every account holder is an individual, `commercial` if every account holder is a business or sole proprietorship. - `account_holders` EntityID[]: Entity IDs of the applicants. - `authorized_signers` EntityID[]: Entity IDs of authorized signers. - `details` ApplicationDetailsV2, required: Underwriting and adverse action notice details. - `underwriting` ApplicationUnderwritingV2: Underwriting inputs and outcomes. - `is_secured` boolean: `true` if collateral secures the product. - `is_mla` boolean: `true` if the applicant is covered by the Military Lending Act. - `currency_code` 'AED' | 'AFN' | 'ALL' | 'AMD' | 'AOA' | 'ARS' | 'AUD' | 'AWG' | 'AZN' | 'BAM' | 'BBD' | 'BDT' | 'BGN' | 'BHD' | 'BIF' | 'BMD' | 'BND' | 'BOB' | 'BRL' | 'BSD' | 'BTN' | 'BWP' | 'BYN' | 'BZD' | 'CAD' | 'CDF' | 'CHF' | 'CLP' | 'CNH' | 'CNY' | 'COP' | 'CRC' | 'CUC' | 'CUP' | 'CVE' | 'CZK' | 'DJF' | 'DKK' | 'DOP' | 'DZD' | 'EGP' | 'ERN' | 'ETB' | 'EUR' | 'FJD' | 'FKP' | 'GBP' | 'GEL' | 'GGP' | 'GHS' | 'GIP' | 'GMD' | 'GNF' | 'GTQ' | 'GYD' | 'HKD' | 'HNL' | 'HTG' | 'HUF' | 'IDR' | 'ILS' | 'IMP' | 'INR' | 'IQD' | 'IRR' | 'ISK' | 'JEP' | 'JMD' | 'JOD' | 'JPY' | 'KES' | 'KGS' | 'KHR' | 'KMF' | 'KPW' | 'KRW' | 'KWD' | 'KYD' | 'KZT' | 'LAK' | 'LBP' | 'LKR' | 'LRD' | 'LSL' | 'LYD' | 'MAD' | 'MDL' | 'MGA' | 'MKD' | 'MMK' | 'MNT' | 'MOP' | 'MRU' | 'MUR' | 'MVR' | 'MWK' | 'MXN' | 'MYR' | 'MZN' | 'NAD' | 'NGN' | 'NIO' | 'NOK' | 'NPR' | 'NZD' | 'OMR' | 'PAB' | 'PEN' | 'PGK' | 'PHP' | 'PKR' | 'PLN' | 'PYG' | 'QAR' | 'RON' | 'RSD' | 'RUB' | 'RWF' | 'SAR' | 'SBD' | 'SCR' | 'SDG' | 'SEK' | 'SGD' | 'SHP' | 'SLE' | 'SOS' | 'SRD' | 'SSP' | 'STD' | 'STN' | 'SVC' | 'SYP' | 'SZL' | 'THB' | 'TJS' | 'TMT' | 'TND' | 'TOP' | 'TRY' | 'TTD' | 'TWD' | 'TZS' | 'UAH' | 'UGX' | 'USD' | 'UYU' | 'UYW' | 'UZS' | 'VES' | 'VND' | 'VUV' | 'WST' | 'XAF' | 'XCD' | 'XCG' | 'XMW' | 'XOF' | 'XPF' | 'YER' | 'ZAR' | 'ZMW' | 'ZWG': A three-letter currency code as defined in ISO 4217 - `underwriting_grade` string: Your internal underwriting grade. - `limit` integer: The credit limit assigned, in minor units. - `max_limit` integer: The highest limit the applicant was approved for in original underwriting, in minor units. - `report` ApplicationCreditReportV2: Credit bureau data, when you sent it. Exactly one of `score` or `non_score_value` is present. - `score` integer: The bureau score, from 300 to 850. - `non_score_value` 'unestablished' | 'frozen': Present when the bureau returned no numeric score. - `pulled_at` string, date-time: When you pulled the report. - `source` 'equifax' | 'experian' | 'transunion': The credit bureau. - `adverse_action_notice` ApplicationAdverseActionNoticeV2: The adverse action notice you sent the applicant. Present on `declined` applications. - `delivered_at` string, date-time: When you sent the notice to the applicant. - `reason` string: The reason stated in the notice. - `delivery_method` 'email' | 'text' | 'other': How you delivered the notice. - `decision` ApplicationDecisionV2: When and why the underwriting decision was made. Absent when `status` is `submitted` or `under_review`. - `decided_at` string, date-time: When you made the underwriting decision. - `reason` string: The reason for the decision. - `exception_approval_reason` string: The reason for approving outside your standard underwriting process. Present only when you sent it. - `documents` FileDocument[], required: Legal or informational documents associated with the application, each referencing a file you uploaded with `POST /v2/files`. Lead accepts only files whose type can link to an application. See the [file type enum list](https://docs.lead.bank/v2/products/files/file-object#the-type-enum). Always an array. - `file_id` string, required: Lead-issued identifier of the file, from `POST /v2/files`. - `timestamp` string, date-time, required: When the end-user was shown or agreed to the document, per the file type. Partner-supplied; records an exchange between the partner and end-user, never upload time. ISO 8601, UTC. - `version` string: Partner-supplied label used for static documents so that two entries of the same type on one object can be ordered (e.g. terms of use v1 and v2). - `legacy_documents` LegacyApplicationDocumentV2[]: Document entries created on v0 Applications, returned exactly as sent. Read only: ignored if included on a POST or PATCH. - `document_id` string: The SFTP filename sent on v0 as the document reference. Lead did not check that the file arrived. - `type` 'aan' | 'loan_agreement' | 'loc_agreement' | 'truth_in_lending_document' | 'ach_authorization' | 'notice_of_incompleteness' | 'credit_score_notice' | 'offer_summary' | 'personal_guarantee' | 'consumer_credit_auth' | 'partner_privacy_policy' | 'lead_privacy_policy' | 'terms_of_use' | 'esign_agreement' | 'credit_pull_consent' | 'fcra_notice' | 'tcpa_consent' | 'patriot_act_notice' | 'mla_notice' | 'pre_approval_terms' | 'eft_authorization' | 'prohibited_industry_certification' | 'decision_maker_document' | 'bo_certification' | 'missed_payments_policy' | 'consent_to_link_account' | 'consent_to_link_hsa' | 'negative_option_consent' | 'lead_funds_transfer_agreement' | 'deposit_agreement' | 'cardholder_agreement' | 'periodic_statement' | 'autopay_authorization': Type of document associated with an application - `displayed_at` string, date-time: When the document was shown to the applicant, as sent on v0. Present on disclosure documents. - `consented_at` string, date-time: When the applicant consented to the document, as sent on v0. Present on consent documents. - `version` string: The version label sent on v0. - `metadata` object: Key-value pairs for your own use. - `created_at` string, date-time, required: When the application was created. RFC 3339, UTC. - `updated_at` string, date-time, required: When the application was last updated. RFC 3339, UTC. ## Other responses - `400`: The request could not be parsed (`request_malformed`), or the `Idempotency-Key` header is missing (`idempotency_key_missing`). - `403`: `code` is one of: `authentication_missing` (the request has no credentials), `token_invalid` (the bearer token is missing, expired, or invalid, or does not grant `application/read_write`), `source_ip_not_permitted` (the request came from an IP address that is not on your program's allowlist). - `409`: A concurrent request with the same `Idempotency-Key` is still in flight. - `413`: The request body is over this endpoint's size limit, for example because `metadata` is too large (`content_too_large`; `errors[].code` is `body_too_large`). - `422`: The request was parsed but cannot be processed. `code` is one of: `parameters_invalid` (a field is missing or invalid; a status-dependent field is missing, like `details.adverse_action_notice` on `declined` (`dependent_parameter_required`); the adverse action notice or credit report is incomplete (`parameter_group_incomplete`); the credit report has neither `score` nor `non_score_value` (`parameter_group_empty`) or both (`parameters_mutually_exclusive`); `limit` exceeds `max_limit` (`parameter_bound_exceeded`); a `documents[].file_id` appears twice, or an entity appears twice in one relationship type (`parameter_duplicated`); a `documents[].timestamp` is more than five minutes in the future (`future_date_not_permitted`); or a commercial `approved` application has no authorized signer. All failures are returned at once), `related_object_invalid` (an entity or a `documents[].file_id` does not exist, or the file belongs to another program; `errors[].code` is `reference_not_found`, with the path in `parameters`), `related_object_not_ready` (on an `approved` application, an entity is not eligible for its relationship type (`entity_role_missing`) or lacks credit data your program requires (`related_object_incomplete`), with the entity's path in `parameters`; update the entity, then retry the request unchanged), `related_object_incompatible` (the account holders mix consumer and commercial entities (`account_holder_types_mismatched`), or an account holder is a lead or partner entity, or a `documents[].file_id` references a file whose type is not a compliance document type (`reference_type_mismatched`)), `lead_control_restricted` (your program is not enabled for Applications v2; `errors[].code` is `feature_not_enabled`), `idempotency_request_mismatched` (this `Idempotency-Key` was used with a different request body). - `429`: Rate limit exceeded. - `500`: Internal server error. Retry with the same `Idempotency-Key`. - `503`: The service or endpoint is temporarily unavailable. Retry after a delay. - `504`: An upstream system did not respond in time. Retry with backoff, and with the same `Idempotency-Key` on a `POST` or `PATCH`. ## Changes - **2026-11-03** `2c659854496e`: 1 info - endpoint added [Operation history](https://skmtc.dev/lead/apis/lead-bank/changes/v2/applications/post.md) --- [API](https://skmtc.dev/lead/apis/lead-bank.md) - [All operations](https://skmtc.dev/lead/apis/lead-bank/llms.txt) - [OpenAPI document](https://skmtc.dev/lead/apis/lead-bank/revisions/2c659854496e?raw)