> ## Documentation Index > Fetch the complete documentation index at: https://docs.nextlevelmca.com/llms.txt > Use this file to discover all available pages before exploring further. # Submit a deal to lenders > Records one submission per lender (a lender-match snapshot is stored with each) and, unless `send` is `false`, sends each one: lenders with `submission_method: "api"` go through their funder integration (the application is queued to the funder’s API; `meta.api_queued` lists them and `api` on the row tracks the attempt), every other lender gets one email through the location’s connected mailbox using the default submission template (or `template_id` / `message_override`) with the chosen documents attached. Queued items come back with `status: "queued"`; poll `GET /submissions/{id}` for `sent`. When no mailbox is connected the email submissions are still recorded (`status: "recorded"`, `meta.warning: "no_email_sender"`) for the team to send from the app. Lenders that already have a submission on the deal are left unchanged and listed in `meta.already_submitted`; lenders without a submissions email, and API lenders whose pre-flight failed (`reason: "api_not_ready"`, see `GET /deals/{dealId}/api-readiness`), are listed in `meta.not_sent`. This sends real email / real applications — **always pass an `Idempotency-Key`** so a retry cannot submit twice. ## OpenAPI ````yaml /openapi/public-v1.json post /v1/deals/{dealId}/submissions openapi: 3.0.0 info: title: NextLevel MCA Public API description: >- REST API for the NextLevel MCA deal platform. Objects flow Businesses → People → Deals → Submissions → Offers → Advances. **Authentication.** Send `Authorization: Bearer ` with an API key (`nlmca_live_…`, created in Settings → Developers) or an OAuth access token. Keys are scoped to one location. **Conventions.** JSON only. Cursor pagination (`limit` ≤ 100, `cursor` from `meta.next_cursor`). Every success is `{ data, meta }`; every error is `{ error: { type, message, code, param, request_id } }`. POST endpoints accept `Idempotency-Key` (24h replay). Rate limit 300 requests/min per credential (`X-RateLimit-*` headers). **Scopes.** Keys with no scopes have all of them. Otherwise: - `businesses:read` — Read businesses and their notes, tasks and activity - `businesses:write` — Create and update businesses, notes and tasks - `people:read` — Read people (contacts and owners) - `people:write` — Create and update people - `deals:read` — Read deals, submissions and the pipeline - `deals:write` — Create and update deals, move stages - `documents:read` — Read documents and statement analysis - `documents:write` — Upload documents and request documents from merchants - `lenders:read` — Read lenders, criteria and lender matches - `lenders:write` — Create and update lenders and criteria - `submissions:write` — Submit deals to lenders and withdraw submissions - `offers:read` — Read offers - `offers:write` — Log and update offers, set the primary offer - `advances:read` — Read funded advances and renewal flags - `advances:write` — Update advances - `portal:send` — Generate and send merchant portal links - `webhooks:manage` — Manage webhook subscriptions - `team:read` — Read team members and their permissions - `team:write` — Add team members and change their roles and permissions version: '1.0' contact: {} servers: - url: https://api.nextlevelmca.com description: Production security: - bearer: [] tags: - name: Businesses description: Merchant businesses and their notes, tasks and activity - name: People description: Contacts and owners. Phone lookups normalise to E.164. - name: Deals description: Deals, stage moves, renewals and the pipeline - name: Documents description: Documents, presigned uploads, document requests and statement analysis - name: Lenders description: Lenders and their criteria - name: Lender matches description: Criteria-driven lender matching for a deal - name: Submissions description: Sending deals to lenders - name: Offers description: Lender offers and the primary offer - name: Advances description: Funded advances and renewal readiness - name: Merchant portal description: Magic links for the merchant portal - name: Webhooks description: Outbound event subscriptions paths: /v1/deals/{dealId}/submissions: post: tags: - Submissions summary: Submit a deal to lenders description: >- Records one submission per lender (a lender-match snapshot is stored with each) and, unless `send` is `false`, sends each one: lenders with `submission_method: "api"` go through their funder integration (the application is queued to the funder’s API; `meta.api_queued` lists them and `api` on the row tracks the attempt), every other lender gets one email through the location’s connected mailbox using the default submission template (or `template_id` / `message_override`) with the chosen documents attached. Queued items come back with `status: "queued"`; poll `GET /submissions/{id}` for `sent`. When no mailbox is connected the email submissions are still recorded (`status: "recorded"`, `meta.warning: "no_email_sender"`) for the team to send from the app. Lenders that already have a submission on the deal are left unchanged and listed in `meta.already_submitted`; lenders without a submissions email, and API lenders whose pre-flight failed (`reason: "api_not_ready"`, see `GET /deals/{dealId}/api-readiness`), are listed in `meta.not_sent`. This sends real email / real applications — **always pass an `Idempotency-Key`** so a retry cannot submit twice. operationId: submissions_create parameters: - name: dealId required: true in: path description: Deal id schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateSubmissionsDto' responses: '201': description: >- One submission per lender; `meta` carries `created`, `already_submitted`, `sending`, `api_queued`, `not_sent`, `warning`. content: application/json: schema: type: object required: - data - meta properties: data: type: array items: $ref: '#/components/schemas/SubmissionDto' meta: type: object additionalProperties: true '400': description: Validation failed. `error.param` names the field. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelopeDto' '401': description: Missing, invalid, expired or revoked credential. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelopeDto' '403': description: Credential lacks the scope, or the role lacks the permission. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelopeDto' '404': description: Resource not found in this location. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelopeDto' '409': description: Conflict (duplicate or idempotency key reuse). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelopeDto' '429': description: Rate limit exceeded. See `X-RateLimit-*` and `Retry-After`. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelopeDto' security: - bearer: [] components: schemas: CreateSubmissionsDto: type: object properties: lender_ids: description: >- Lenders to submit to (1–50). Lenders that already have a submission on this deal are returned unchanged and listed in `meta.already_submitted`. type: array items: type: string document_ids: description: Documents on this deal to attach to the email. Defaults to none. type: array items: type: string template_id: type: string description: >- Email template to use. Defaults to the location’s default submission template. message_override: type: string description: >- Replaces the template body (HTML or plain text). Template variables such as `{{business_name}}` and `{{lender_name}}` are still rendered. maxLength: 50000 subject_override: type: string description: Replaces the template subject. maxLength: 500 send: type: boolean default: true description: >- `true` (default) queues one email per lender through the location’s connected mailbox — or, for lenders with `submission_method: "api"`, sends the application through the funder’s API integration. `false` only records the submissions as `pending` for the team to send from the app. required: - lender_ids SubmissionDto: type: object properties: id: type: string description: Submission id. deal_id: type: string description: Deal that was submitted. lender_id: type: string description: Lender it was submitted to. lender_name: type: string nullable: true description: Lender name at read time. status: type: string enum: - pending - queued - recorded - sent - approved - declined - needs_info - expired - funded - withdrawn description: >- `pending` = recorded, not sent yet · `sent` = emailed or accepted by the funder’s API · `approved`/`declined`/`needs_info` = lender responded · `funded` = advance created · `expired` · `withdrawn`. submission_method: type: string enum: - email - api description: >- How this lender receives submissions: `email`, or `api` through a funder integration (then `api` carries the attempt). api: nullable: true description: >- Latest attempt through the lender’s API integration; null for email lenders or before the first API attempt. allOf: - $ref: '#/components/schemas/ApiSubmissionDto' response_type: type: string nullable: true description: >- Lender response kind when classified: `approved`, `declined`, `counter`, `more_info`, `withdrawn`. response_notes: type: string nullable: true description: Notes from the lender response. decline_reason: type: string nullable: true description: Decline reason text. decline_category: type: string nullable: true description: Decline category slug. requested_items: description: Items the lender asked for (`needs_info`). type: array items: type: string match_score: type: number nullable: true description: >- Lender-match score (0–100) snapshotted when the submission was created. match_eligible: type: boolean nullable: true description: Whether the deal passed the lender’s hard gates at submission time. submitted_by_id: type: string nullable: true description: User id that submitted (null for API keys without a creator). submitted_at: type: string nullable: true description: When the email went out (ISO 8601). responded_at: type: string nullable: true description: When the lender responded (ISO 8601). trace_code: type: string nullable: true example: K7M3QX description: >- Document reference stamped on every page of the package emailed to this lender (shown as `Ref K7M-3QX` in the footer, and in the PDF keywords). Unique per submission. Resolve one with `GET /v1/submissions/by-reference/{code}`. Null until the package is sent. created_at: type: string description: Creation time (ISO 8601). updated_at: type: string nullable: true description: Last update time (ISO 8601). required: - id - deal_id - lender_id - lender_name - status - submission_method - api - response_type - response_notes - decline_reason - decline_category - requested_items - match_score - match_eligible - submitted_by_id - submitted_at - responded_at - trace_code - created_at - updated_at ErrorEnvelopeDto: type: object properties: error: $ref: '#/components/schemas/PublicErrorDto' required: - error ApiSubmissionDto: type: object properties: id: type: string description: Attempt id. submission_id: type: string description: Submission the attempt belongs to. deal_id: type: string description: Deal id. lender_id: type: string description: Lender id. funder_api_spec_id: type: string description: >- Funder integration used, e.g. `mock`, `ondeck` (see `GET /lenders/api-specs`). environment: type: string enum: - development - production description: >- Funder environment the attempt went to. `development` never reaches real underwriting. external_id: type: string nullable: true description: >- Funder’s application / reference id once it acknowledged the application. funder_status: type: string nullable: true description: Funder’s status string, verbatim (e.g. `Credit Review`). internal_status: type: string enum: - queued - sent - pending - approved - declined - funded - errored - expired - stale description: >- `queued` = waiting to be sent · `sent` / `pending` = at the funder · `approved` / `declined` / `funded` / `expired` = decided · `errored` = the last attempt failed (see `error_code`; the funder may still have received it — use check-status) · `stale` = polling stopped after 7 days. deep_link_url: type: string nullable: true description: Link to the application in the funder’s portal. error_message: type: string nullable: true description: Funder’s error message, verbatim. error_code: type: string nullable: true enum: - auth_failed - validation - timeout - funder_error - network - config - unconfirmed description: >- `auth_failed` = credentials rejected (never retried automatically) · `validation` = the funder rejected fields (never retried) · `timeout` / `network` / `funder_error` = transport or 5xx (retried with backoff) · `config` = the lender is not set up · `unconfirmed` = the funder answered as if it took the application but without a reference we could read, so it may have it: never retried, and `retry` is refused (check with the lender; the team can send it again from the app once the lender confirms it doesn’t have it). attempt_number: type: number description: Attempt number for this submission (1 = first). submitted_at: type: string nullable: true description: When the request went to the funder (ISO 8601). last_polled_at: type: string nullable: true description: Last status check (ISO 8601). next_poll_at: type: string nullable: true description: >- Next scheduled status check (ISO 8601). Null when polling is finished. created_at: type: string description: Creation time (ISO 8601). updated_at: type: string nullable: true description: Last update time (ISO 8601). can_retry: type: boolean description: >- Whether `POST /submissions/{id}/retry` would pass the duplicate guard now: the last attempt is `errored` (not `unconfirmed`) or `stale`, at least 2 minutes have passed since it was sent, and the lender hasn’t answered (the submission isn’t `approved`, `needs_info` or `funded`, and the lender has no live offer on the deal). The same rule as `retry`, so `false` predicts its 409 `retry_blocked`; `retry_blocked_reason` says why. Pre-flight (400 `not_ready`) and a switched-off integration are checked only when you call it. retry_after_seconds: type: number nullable: true description: >- Seconds until a retry is allowed when only the 2-minute guard blocks it. Null otherwise (allowed now, or blocked for a reason waiting won’t fix). retry_blocked_reason: type: string nullable: true description: >- Why `retry` would be refused now, in plain words (the 409 message). Null when `can_retry` is true. required: - id - submission_id - deal_id - lender_id - funder_api_spec_id - environment - external_id - funder_status - internal_status - deep_link_url - error_message - error_code - attempt_number - submitted_at - last_polled_at - next_poll_at - created_at - updated_at - can_retry - retry_after_seconds - retry_blocked_reason PublicErrorDto: type: object properties: type: type: string enum: - validation_error - authentication_error - permission_error - not_found - conflict - rate_limit_error - api_error message: type: string description: Human-readable explanation, safe to show to an operator or an agent. code: type: string description: >- Stable machine-readable code, e.g. `missing_scope`, `duplicate_business`. param: type: string description: Request field the error refers to, when applicable. request_id: type: string description: Echo of the `X-Request-Id` header. Quote it when contacting support. required: - type - message - request_id securitySchemes: bearer: scheme: bearer bearerFormat: API key or JWT type: http description: API key (`nlmca_live_…`) or OAuth access token ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.