--- title: "Update an application" method: PATCH path: "/v2/applications/{id}" tags: ["Application"] --- # Update an application `PATCH /v2/applications/{id}` ## Request - Base URL: `https://api.sandbox.lead.bank` - URL: `https://api.sandbox.lead.bank/v2/applications/{id}` - Auth: HTTP bearer Update the product name, details, decision, documents, or metadata on an Application. See [Create and update](/v2/products/applications/application-object#create-and-update) for how `PATCH` handles each field. ## Path parameters - `id` string, required: Unique identifier for the application. Prefixed with `application_`. ## Headers - `Idempotency-Key` string, required ## Request body - UpdateApplicationRequestBodyV2: Request body for `PATCH /v2/applications/{id}`. Omitted fields are unchanged, and nested objects merge. `null` is not accepted, so a field cannot be cleared once set. `status` is accepted and ignored: status cannot change after creation, so a `PATCH` that includes `status` returns `200` and leaves the status unchanged. `entities` cannot change after creation. Lead ignores `entities`, `client_application_id`, `legacy_documents`, and any other field this endpoint does not define, if sent. - `status` 'approved' | 'declined' | 'canceled' | 'submitted' | 'under_review': 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: Your internal product name. - `details` UpdateApplicationDetailsV2: Details to change. Nested objects merge; omitted fields are unchanged. - `underwriting` UpdateApplicationUnderwritingV2: Underwriting fields to change. Omitted fields are unchanged. - `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. Any string. - `limit` integer: The credit limit assigned, in minor units. Cannot exceed `max_limit`. - `max_limit` integer: The highest limit the applicant was approved for in original underwriting, in minor units. - `report` UpdateCreditReportV2: Credit report fields to change. Fields you send replace the stored values; omitted fields are unchanged. The resulting report must still have `pulled_at`, `source`, and exactly one of `score` or `non_score_value`. - `score` integer: The bureau score, from 300 to 850. - `non_score_value` 'unestablished' | 'frozen': Sent 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` UpdateAdverseActionNoticeV2: Adverse action notice fields to change. Fields you send replace the stored values; omitted fields are unchanged. On a `declined` application the resulting notice must still have all three fields. - `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` UpdateDecisionV2: Decision fields to change. Fields you send replace the stored values; omitted fields are unchanged. - `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. - `documents` FileDocument[]: 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. To add a document, send every existing entry plus the new one. - `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 updated. - 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). - `404`: No application exists with this ID, or it is not visible to your program. - `409`: `code` is one of: `idempotency_key_in_use` (a concurrent request with the same `Idempotency-Key` is still in flight), `object_modified_concurrently` (another request changed the application while this one was processing; fetch it and retry). - `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 invalid; a status-dependent field is missing (`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`); the updated `limit` exceeds `max_limit` (`parameter_bound_exceeded`); a `documents[].file_id` appears twice (`parameter_duplicated`); or a `documents[].timestamp` is more than five minutes in the future (`future_date_not_permitted`). All failures are returned at once), `related_object_invalid` (a `documents[].file_id` does not exist or 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 no longer 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` (a `documents[].file_id` references a file whose type is not a compliance document type; `errors[].code` is `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/:id/patch.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)