> ## Documentation Index > Fetch the complete documentation index at: https://docs.lead.bank/llms.txt > Use this file to discover all available pages before exploring further. # Create an Application > Creates a new credit application in terminal status. ## Business Rules - Applications MUST be created in terminal status (approved, declined, canceled) - Maximum 20 entities per relationship type - Credit fields required for all applications - Adverse action notice required for declined applications - Authorized signers required for commercial account holders - client_application_id cannot start with reserved prefix 'application_' - credit.limit cannot exceed credit.max_limit ## Idempotency The Idempotency-Key header is required. Reusing a key with a different request body will return a 422 error. ## OpenAPI ````yaml POST /v0/applications openapi: 3.0.1 info: title: Lead Bank description: Lead Bank's APIs version: v1.0 servers: - url: https://api.sandbox.lead.bank - url: https://api.lead.bank security: - bearerAuth: [] tags: - name: ACH - name: Account Number - name: OAuth - name: Events - name: Instant Payments - name: Lending - name: Simulation - name: Internal Transfer - name: Disbursement - name: Entity - name: Wire - name: Originator - name: Funding - name: Balances - name: Compliance - name: UserAccount - name: Blockchain Payment paths: /v0/applications: post: tags: - Compliance summary: Create an application description: > Creates a new credit application in terminal status. ## Business Rules - Applications MUST be created in terminal status (approved, declined, canceled) - Maximum 20 entities per relationship type - Credit fields required for all applications - Adverse action notice required for declined applications - Authorized signers required for commercial account holders - client_application_id cannot start with reserved prefix 'application_' - credit.limit cannot exceed credit.max_limit ## Idempotency The Idempotency-Key header is required. Reusing a key with a different request body will return a 422 error. operationId: create-an-application parameters: - name: Idempotency-Key in: header required: true description: Unique key to ensure idempotent requests schema: type: string maxLength: 255 example: app-create-12345-abc requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateApplicationRequest' examples: approved_commercial: summary: Approved commercial application value: client_application_id: APP-2024-001 status: approved entities: account_holder_type: commercial account_holders: - entity_123456789 authorized_signers: - entity_987654321 details: product_name: Growth Business Credit Line credit: is_secured: true is_mla: false currency: USD underwriting_grade: '99' limit: 5000000 max_limit: 10000000 report: score: 780 pulled_at: '2025-11-15T09:30:00Z' source: experian decision: decided_at: '2025-11-17T14:00:00Z' reason: Approved based on strong cash flow and collateral. exception_approval_reason: Manual override of automated debt-to-income threshold. documents: - document_id: doc_consent_001 type: credit_pull_consent consented_at: '2025-11-15T09:00:00Z' declined_consumer: summary: Declined consumer application value: client_application_id: APP-2024-002 status: declined entities: account_holder_type: consumer account_holders: - entity_consumer_555000111 details: product_name: Everyday Consumer Card credit: is_secured: false is_mla: true currency: USD underwriting_grade: D limit: 0 max_limit: 0 report: score: 580 pulled_at: '2025-11-16T10:15:00Z' source: transunion adverse_action_notice: delivered_at: '2025-11-16T10:17:00Z' reason: Delinquent past credit obligations. delivery_method: email decision: decided_at: '2025-11-16T10:16:00Z' reason: Does not meet minimum credit score requirements. documents: - document_id: doc_aan_999 type: aan displayed_at: '2025-11-16T10:17:00Z' canceled_commercial: summary: Canceled commercial application value: client_application_id: APP-2024-003 status: canceled entities: account_holder_type: commercial account_holders: - entity_biz_777888999 authorized_signers: - entity_person_111222333 details: product_name: Secured Starter Loan credit: is_secured: true is_mla: false currency: USD limit: 0 max_limit: 0 decision: decided_at: '2025-11-17T08:00:00Z' reason: Applicant withdrew request. documents: [] responses: '200': description: Application created successfully. content: application/json: schema: $ref: '#/components/schemas/Application' '400': description: Malformed request or missing required header. content: application/json: schema: $ref: '#/components/schemas/APIError' examples: invalid_json: summary: Malformed JSON value: code: payload_invalid title: Your request body did not parse. detail: >- We couldn't parse your request body, please check that your request body is valid JSON. invalid_parameters: [] missing_idempotency_key: summary: Missing Idempotency-Key header value: code: idempotency_error title: A required HTTP header is missing. detail: Please add the Idempotency-Key header to the request. invalid_parameters: [] '401': description: Valid access token was not used to call the API. content: application/json: schema: $ref: '#/components/schemas/APIError' '403': description: Valid access token lacks the proper scopes. content: application/json: schema: $ref: '#/components/schemas/APIError' '409': description: An application with the same data already exists. content: application/json: schema: $ref: '#/components/schemas/APIError' '422': description: Request validation failed. content: application/json: schema: $ref: '#/components/schemas/APIError' examples: missing_required_fields: summary: Missing required parameters value: code: parameters_invalid title: Your request parameters did not validate. detail: The request is well-formed but contains semantic errors. invalid_parameters: - name: status reason: missing - name: entities reason: missing invalid_client_id_prefix: summary: Invalid client_application_id prefix value: code: parameters_invalid title: Your request parameters did not validate. detail: >- client_application_id cannot start with the reserved prefix 'application_'. invalid_parameters: - name: client_application_id reason: invalid_namespace missing_aan_for_declined: summary: Missing adverse action notice for declined status value: code: parameters_invalid title: Your request parameters did not validate. detail: >- details.decision.adverse_action_notice is required when status is 'declined'. invalid_parameters: - name: details.decision.adverse_action_notice reason: missing_for_status_declined missing_decision_reason: summary: Missing decision reason value: code: parameters_invalid title: Your request parameters did not validate. detail: >- details.decision.reason is required when status is 'approved', 'declined', or 'canceled'. invalid_parameters: - name: details.decision.reason reason: missing entity_not_found: summary: Entity ID not found value: code: parameters_invalid title: Your request parameters did not validate. detail: >- No Entity exists for the provided entity_id 'entity_123...' invalid_parameters: - name: entities.account_holders[0] reason: not_found limit_exceeds_max: summary: Credit limit exceeds max limit value: code: parameters_invalid title: Your request parameters did not validate. detail: >- credit_limit (10000) cannot exceed max_credit_limit (5000). invalid_parameters: - name: details.credit.limit reason: exceeds_max_limit idempotency_mismatch: summary: Idempotency key reused with different request value: code: idempotency_request_inconsistent title: >- The request made does not match the previous request made with this idempotency key. detail: >- If you are trying to make a new request, then please update the idempotency key; otherwise, please use the same request body to make this request. invalid_parameters: [] '429': description: Rate limit exceeded. content: application/json: schema: $ref: '#/components/schemas/APIError' example: code: rate_limit_exceeded title: You've reached the rate limit for this call. detail: >- If you are continuously hitting rate limits please contact the Lead team. invalid_parameters: [] '500': description: Server error. Please try your request again. content: application/json: schema: $ref: '#/components/schemas/APIError' components: schemas: CreateApplicationRequest: type: object description: Request body for creating a new application in terminal status properties: status: $ref: '#/components/schemas/ApplicationStatus' entities: $ref: '#/components/schemas/CreateApplicationEntities' details: $ref: '#/components/schemas/CreateApplicationDetails' decision: $ref: '#/components/schemas/Decision' documents: type: array description: Documents associated with the application items: $ref: '#/components/schemas/CreateComplianceDocument' metadata: type: object description: Arbitrary metadata associated with the application additionalProperties: type: string required: - status - entities - details - decision - documents Application: type: object description: An application object representing a credit application readOnly: true properties: id: $ref: '#/components/schemas/ApplicationID' client_application_id: type: string readOnly: true description: > Client-provided identifier for the application. Optional: present only for applications created via file upload, and omitted for applications created through the API, which are identified solely by their server-generated ID. created_at: type: string format: date-time description: >- Lead server-generated ISO 8601 timestamp when the application was created. updated_at: type: string format: date-time description: >- Lead server-generated ISO 8601 timestamp when the application was last updated. status: $ref: '#/components/schemas/ApplicationStatus' entities: $ref: '#/components/schemas/ApplicationEntities' details: $ref: '#/components/schemas/ApplicationDetails' decision: $ref: '#/components/schemas/ApplicationDecision' documents: type: array description: Documents associated with the application items: $ref: '#/components/schemas/ApplicationComplianceDocument' metadata: type: object description: Arbitrary metadata associated with the application additionalProperties: type: string APIError: type: object properties: code: type: string description: The error code. title: type: string description: The error title. detail: type: string description: A detailed error description. status: type: string description: The HTTP status code. invalid_parameters: type: array description: Invalid request parameters with reasons, if applicable. items: $ref: '#/components/schemas/InvalidParameterDetail' instance: type: string description: >- The object causing this specific occurrence of the error, if applicable. ApplicationStatus: type: string description: >- Terminal state of the application. Possible values: `approved`, `declined`, `canceled`. enum: - approved - declined - canceled CreateApplicationEntities: type: object description: | Entity relationships for the application. Maximum 20 entities per relationship type. Authorized signers required for commercial account holders. properties: account_holders: type: array description: List of entity IDs that are account holders items: $ref: '#/components/schemas/EntityID' minItems: 1 maxItems: 20 authorized_signers: type: array description: >- List of entity IDs that are authorized signers (required for commercial) items: $ref: '#/components/schemas/EntityID' maxItems: 20 authorized_users: type: array description: List of entity IDs that are authorized users items: $ref: '#/components/schemas/EntityID' maxItems: 20 required: - account_holders CreateApplicationDetails: type: object description: Details for creating an application properties: product_name: type: string description: >- Your internal product name. This tells Lead's Due Diligence team which product this application, if approved, would open an account for. example: Growth Business Credit Line credit: $ref: '#/components/schemas/CreateApplicationCredit' adverse_action_notice: $ref: '#/components/schemas/AdverseActionNotice' required: - product_name - credit Decision: type: object description: Decision-related information for the application properties: decided_at: type: string format: date-time description: ISO 8601 timestamp when the underwriting decision was made. reason: type: string description: The reason for the decision. exception_approval_reason: type: string description: >- This should only be provided if the decision was made as an exception to underwriting criteria. Reason for exception approval, if this decision was made as an exception to the traditional underwriting process. required: - decided_at - reason CreateComplianceDocument: type: object description: > Document reference for creating applications and accounts. One of `displayed_at` or `consented_at` is required depending on document type: - `displayed_at`: Required for 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, 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, lead_funds_transfer_agreement - `consented_at`: Required for esign_agreement, credit_pull_consent, consent_to_link_account, consent_to_link_hsa, negative_option_consent properties: document_id: type: string description: >- Unique identifier for the document being referenced. Please use the file name of the file delivered to Lead's `/documents` SFTP directory. example: document_2N5Hk8xYmQpL9rBvC3jD type: $ref: '#/components/schemas/ComplianceDocumentType' displayed_at: type: string format: date-time description: >- ISO 8601 timestamp when the document was displayed to the applicant. Present on disclosure documents. consented_at: type: string format: date-time description: >- ISO 8601 timestamp when the applicant consented to the document. Present on consent documents. version: type: string description: >- It is recommended to use this for static documents uploaded once and uploaded for many users. Uploads with a new version should have a different document_id as well. example: v1 required: - document_id - type oneOf: - title: Disclosure description: Disclosure document — `displayed_at` is required. properties: type: type: string enum: - 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 - 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 - lead_funds_transfer_agreement required: - displayed_at - title: Consent description: Consent document — `consented_at` is required. properties: type: type: string enum: - esign_agreement - credit_pull_consent - consent_to_link_account - consent_to_link_hsa - negative_option_consent required: - consented_at ApplicationID: type: string description: Unique identifier for the application. Prefixed with `application_`. example: application_xyz123 pattern: ^application_\w+$ ApplicationEntities: type: object readOnly: true description: Entity relationships associated with the application (response only) properties: account_holder_type: type: string description: >- Denotes whether the application is for a consumer or commercial account. `consumer` if all account holders are individuals; `commercial` if all account holders are businesses or sole proprietors. enum: - consumer - commercial example: commercial account_holders: type: array description: List of entity IDs that are account holders items: $ref: '#/components/schemas/EntityID' authorized_signers: type: array description: List of entity IDs that are authorized signers items: $ref: '#/components/schemas/EntityID' ApplicationDetails: type: object readOnly: true description: Application details (response, all properties optional) properties: product_name: type: string description: >- Your internal product name. This tells Lead's Due Diligence team which product this application, if approved, would open an account for. example: Growth Business Credit Line credit: $ref: '#/components/schemas/ApplicationCredit' adverse_action_notice: $ref: '#/components/schemas/ApplicationAdverseActionNotice' ApplicationDecision: type: object readOnly: true description: Decision-related information (response, all properties optional) properties: decided_at: type: string format: date-time description: ISO 8601 timestamp when the underwriting decision was made. reason: type: string description: The reason for the decision. exception_approval_reason: type: string description: >- This should only be provided if the decision was made as an exception to underwriting criteria. Reason for exception approval, if this decision was made as an exception to the traditional underwriting process. ApplicationComplianceDocument: type: object readOnly: true description: >- Document reference associated with an application (response, all properties optional) properties: document_id: type: string description: >- Unique identifier for the document being referenced. Please use the file name of the file delivered to Lead's `/documents` SFTP directory. example: document_2N5Hk8xYmQpL9rBvC3jD type: $ref: '#/components/schemas/ComplianceDocumentType' displayed_at: type: string format: date-time description: >- ISO 8601 timestamp when the document was displayed to the applicant. Present on disclosure documents. consented_at: type: string format: date-time description: >- ISO 8601 timestamp when the applicant consented to the document. Present on consent documents. version: type: string description: >- It is recommended to use this for static documents uploaded once and uploaded for many users. Uploads with a new version should have a different document_id as well. example: v1 InvalidParameterDetail: type: object properties: parameter: type: string description: Which parameter is invalid. example: transaction_type reason: type: string description: Why the parameter is invalid. EntityID: type: string description: The ID of your entity. example: entity_xyz123 pattern: ^entity_[^\s]{1,33}$ CreateApplicationCredit: type: object description: Credit details for creating an application properties: is_secured: type: boolean description: >- Indicates if this is a secured credit/deposit product. `true` if the product is secured (collateral attached); `false` otherwise. is_mla: type: boolean description: >- `true` if the applicant is subject to the Military Lending Act; `false` otherwise. currency: $ref: '#/components/schemas/ComplianceCurrencyCode' underwriting_grade: type: string description: >- Your internal underwriting grade for the applicant. Accepts any string mapped to your specific scoring framework. example: '99' limit: type: integer description: >- The credit limit assigned to the applicant, in minor units (e.g., cents). minimum: 0 example: 5000000 max_limit: type: integer description: >- The maximum credit limit the applicant was approved for based on original underwriting, in minor units (e.g., cents). minimum: 0 example: 10000000 report: $ref: '#/components/schemas/CreditReport' required: - is_secured - is_mla - currency AdverseActionNotice: type: object description: Adverse action notice information properties: delivered_at: type: string format: date-time description: >- ISO 8601 timestamp when the adverse action notice was sent to the applicant. reason: type: string description: The reason stated in the adverse action notice. delivery_method: type: string description: >- How the notice was delivered to the applicant. Possible values: `email`, `text`, `other`. enum: - email - text - other required: - delivered_at - reason - delivery_method ComplianceDocumentType: type: string description: Type of document associated with an application enum: - 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 ApplicationCredit: type: object readOnly: true description: Credit details for an application (response, all properties optional) properties: is_secured: type: boolean description: >- Indicates if this is a secured credit/deposit product. `true` if the product is secured (collateral attached); `false` otherwise. is_mla: type: boolean description: >- `true` if the applicant is subject to the Military Lending Act; `false` otherwise. currency: $ref: '#/components/schemas/ComplianceCurrencyCode' underwriting_grade: type: string description: >- Your internal underwriting grade for the applicant. Accepts any string mapped to your specific scoring framework. example: '99' limit: type: integer description: >- The credit limit assigned to the applicant, in minor units (e.g., cents). minimum: 0 example: 5000000 max_limit: type: integer description: >- The maximum credit limit the applicant was approved for based on original underwriting, in minor units (e.g., cents). minimum: 0 example: 10000000 report: $ref: '#/components/schemas/ApplicationCreditReport' ApplicationAdverseActionNotice: type: object readOnly: true description: Adverse action notice information (response, all properties optional) properties: delivered_at: type: string format: date-time description: >- ISO 8601 timestamp when the adverse action notice was sent to the applicant. reason: type: string description: The reason stated in the adverse action notice. delivery_method: type: string description: >- How the notice was delivered to the applicant. Possible values: `email`, `text`, `other`. enum: - email - text - other ComplianceCurrencyCode: type: string description: A three-letter currency code as defined in ISO 4217 enum: - 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 CreditReport: type: object description: > Credit report information. Exactly one of `score` or `non_score_value` must be provided; `pulled_at` and `source` are always required when a credit report is supplied. required: - pulled_at - source properties: score: type: integer description: >- Credit score returned by the bureau. Supported range is 300-850. Mutually exclusive with `non_score_value`. minimum: 300 maximum: 850 non_score_value: type: string description: >- Indicates the state of a credit file when a numeric score is not available. Mutually exclusive with `score`. enum: - unestablished - frozen pulled_at: type: string format: date-time description: ISO 8601 timestamp when the credit report was pulled. source: type: string description: >- Credit bureau that issued the report. Possible values: `equifax`, `experian`, `transunion`. enum: - equifax - transunion - experian ApplicationCreditReport: type: object readOnly: true description: Credit report information (response, all properties optional) properties: score: type: integer description: >- Credit score returned by the bureau. Supported range is 300-850. Mutually exclusive with `non_score_value`. minimum: 300 maximum: 850 non_score_value: type: string description: >- Indicates the state of a credit file when a numeric score is not available. Mutually exclusive with `score`. enum: - unestablished - frozen pulled_at: type: string format: date-time description: ISO 8601 timestamp when the credit report was pulled. source: type: string description: >- Credit bureau that issued the report. Possible values: `equifax`, `experian`, `transunion`. enum: - equifax - transunion - experian securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT ````