> ## 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. # Move a deal to a stage, mark it funded, or mark it dead > Send `{ stage_id }` for a manual move (board rules apply: stages fed by workflow events are blocked, Funded needs a funded offer, Dead needs `reason`; violations are 400 `stage_rule` with the app’s own message). Send `{ event: "mark_funded", funded: {…} }` to fund the primary offer (or `funded.offer_id`), which creates the advance, commission records and moves the deal to Funded. Send `{ event: "mark_dead", reason }` to close the deal out and move it to Dead. An optional `note` is added to the timeline either way. ## OpenAPI ````yaml /openapi/public-v1.json post /v1/deals/{id}/stage 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 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/{id}/stage: post: tags: - Deals summary: Move a deal to a stage, mark it funded, or mark it dead description: >- Send `{ stage_id }` for a manual move (board rules apply: stages fed by workflow events are blocked, Funded needs a funded offer, Dead needs `reason`; violations are 400 `stage_rule` with the app’s own message). Send `{ event: "mark_funded", funded: {…} }` to fund the primary offer (or `funded.offer_id`), which creates the advance, commission records and moves the deal to Funded. Send `{ event: "mark_dead", reason }` to close the deal out and move it to Dead. An optional `note` is added to the timeline either way. operationId: deals_changeStage parameters: - name: id required: true in: path description: Deal id schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/DealStageChangeDto' responses: '200': description: OK content: application/json: schema: type: object required: - data - meta properties: data: $ref: '#/components/schemas/DealStageChangeResultDto' meta: $ref: '#/components/schemas/EmptyMetaDto' '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: DealStageChangeDto: type: object properties: stage_id: type: string description: >- Move to this stage (ids from `GET /v1/pipeline`). Board rules apply: stages fed by workflow events cannot be entered manually, the Funded stage needs a funded offer, the Dead stage needs `reason`. Rule violations are 400 `stage_rule` with the same message the app shows. event: type: string enum: - mark_funded - mark_dead description: >- Instead of `stage_id`: `mark_funded` funds an offer (send `funded`) and moves the deal to Funded; `mark_dead` closes the deal out (send `reason`) and moves it to Dead. funded: description: 'Required with `event: mark_funded`.' allOf: - $ref: '#/components/schemas/DealFundedInputDto' reason: type: string maxLength: 1000 description: >- Why. Required with `event: mark_dead` and when moving into the Dead stage by `stage_id`. note: type: string maxLength: 10000 description: Optional note added to the deal timeline alongside the move. DealStageChangeResultDto: type: object properties: moved: type: boolean description: False when the deal was already in the target stage. outcome: type: string enum: - moved - same_stage - not_forward - event_unbound - no_stages description: >- `event_unbound` means the location has no stage bound to the event (the status still changed). from_stage: nullable: true allOf: - $ref: '#/components/schemas/DealStageDto' to_stage: nullable: true allOf: - $ref: '#/components/schemas/DealStageDto' event: type: string nullable: true description: >- System event that was published (`marked_funded`, `marked_dead`), or null for a manual move. deal: description: The deal after the change. allOf: - $ref: '#/components/schemas/DealDto' required: - moved - outcome - from_stage - to_stage - event - deal EmptyMetaDto: type: object properties: {} ErrorEnvelopeDto: type: object properties: error: $ref: '#/components/schemas/PublicErrorDto' required: - error DealFundedInputDto: type: object properties: offer_id: type: string description: >- Offer being funded. Defaults to the deal’s primary offer (409 `no_primary_offer` when there is none). funded_amount: type: number minimum: 0 description: Amount funded, in dollars. payback_amount: type: number minimum: 0 description: Total payback, in dollars. term: type: number minimum: 1 description: Term length (in the offer’s term unit, usually months). payment_amount: type: number minimum: 0 description: Amount per payment, in dollars. funded_date: type: string description: Funding date, ISO 8601 (`YYYY-MM-DD` accepted). example: '2026-09-15' factor_rate: type: number description: Factor rate, e.g. `1.35`. payment_frequency: type: string enum: - daily - weekly - bi-weekly - monthly points: type: number description: >- Commission points (%) earned from the lender; creates the commission record. psf: type: number description: >- Professional service fee charged to the merchant (flat dollars, or percent when `psf_is_percent`). psf_is_percent: type: boolean description: Treat `psf` as a percentage of the funded amount. commission_expected_date: type: string description: When the commission is expected, ISO 8601. required: - funded_amount - payback_amount - term - payment_amount - funded_date DealStageDto: type: object properties: id: type: string description: Stage id. label: type: string description: Label as shown on the board. phase: type: string enum: - preoffer - offer - contract - funded - dead description: Phase the stage belongs to. sort_order: type: number description: Board order (ascending). event: type: string nullable: true enum: - first_submission_sent - first_offer_logged - merchant_accepted_offer - contracts_requested - contracts_sent - contracts_signed - marked_funded - marked_dead description: System event bound to this stage, when it is event-driven. required: - id - label - phase - sort_order - event DealDto: type: object properties: id: type: string description: Deal id. business_id: type: string nullable: true description: >- Business the deal belongs to (null only for legacy deals that were never linked). business: nullable: true description: Linked business summary. Use `include=business` for the full record. allOf: - $ref: '#/components/schemas/DealBusinessSummaryDto' business_name: type: string nullable: true description: Business name as captured on the application. dba: type: string nullable: true entity_type: type: string nullable: true industry: type: string nullable: true business_address: type: string nullable: true business_city: type: string nullable: true business_state: type: string nullable: true business_zip: type: string nullable: true business_phone: type: string nullable: true business_start_date: type: string nullable: true description: '`YYYY-MM-DD`.' state_incorporated: type: string nullable: true owner: nullable: true description: >- Primary owner as captured on the application. Use `include=people` for linked person records. allOf: - $ref: '#/components/schemas/DealOwnerSummaryDto' requested_amount: type: number nullable: true description: Requested funding amount in dollars. annual_revenue: type: number nullable: true description: Stated annual revenue in dollars. use_of_funds: type: string nullable: true product_type: type: string nullable: true enum: - mca - term_loan - loc - equipment - factoring desired_term_months: type: number nullable: true desired_frequency: type: string nullable: true enum: - daily - weekly - bi-weekly - monthly paper_grade: type: string nullable: true description: Paper grade `A`–`D`. paper_grade_source: type: string nullable: true description: '`computed` (from bank data and risk flags) or `manual` (overridden).' risk_flags: type: object description: >- Rep-entered risk facts: `{ prior_default, reversals, bankruptcy_months, seasonal, franchise_years }`. status: type: string nullable: true description: >- Deal status slug (e.g. `new`, `submitted`, `approved`, `sold`, `funded`, `closed_out`). Stages are the v2 view of the same progression. stage: nullable: true description: Current pipeline stage. allOf: - $ref: '#/components/schemas/DealStageDto' stage_entered_at: type: string nullable: true description: When the deal entered its current stage (ISO 8601 UTC). days_in_stage: type: number nullable: true description: Whole days in the current stage. primary_offer: nullable: true description: >- The primary offer, when one is set. Its status drives the deal status. allOf: - $ref: '#/components/schemas/DealPrimaryOfferDto' originator: nullable: true description: Assigned originator. allOf: - $ref: '#/components/schemas/DealUserDto' closer: nullable: true description: Assigned closer. allOf: - $ref: '#/components/schemas/DealUserDto' source: type: string nullable: true description: >- How the deal was created: `api`, `user_created`, `embed_form`, `workflow`, `renewal`, … lead_source: type: string nullable: true description: Where the lead came from, free text. form_data: type: object description: >- Application form data keyed by field key (custom fields included). Keys that look like SSNs, tax ids, bank account or routing numbers, passwords or secrets are removed. Update with a merge-patch via `PATCH /v1/deals/{id}`. submissions_count: type: number description: Number of lender submissions. offers_count: type: number description: Number of offers logged. renewal_of_deal_id: type: string nullable: true description: 'For renewals: the deal being renewed.' renewal_of_advance_id: type: string nullable: true description: 'For renewals: the advance being renewed.' manually_closed: type: boolean description: True when the deal was closed manually after funding. closed_at: type: string nullable: true description: ISO 8601 UTC. closed_reason: type: string nullable: true description: Reason given when the deal was marked dead. ghl_contact_id: type: string nullable: true description: CRM contact id of the primary owner. Read-only. ghl_opportunity_id: type: string nullable: true description: CRM opportunity id, when one exists. Read-only. created_at: type: string description: ISO 8601 UTC. updated_at: type: string description: ISO 8601 UTC. required: - id - business_id - business - business_name - dba - entity_type - industry - business_address - business_city - business_state - business_zip - business_phone - business_start_date - state_incorporated - owner - requested_amount - annual_revenue - use_of_funds - product_type - desired_term_months - desired_frequency - paper_grade - paper_grade_source - risk_flags - status - stage - stage_entered_at - days_in_stage - primary_offer - originator - closer - source - lead_source - form_data - submissions_count - offers_count - renewal_of_deal_id - renewal_of_advance_id - manually_closed - closed_at - closed_reason - ghl_contact_id - ghl_opportunity_id - created_at - updated_at 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 DealBusinessSummaryDto: type: object properties: id: type: string description: Business id. legal_name: type: string description: Legal name. dba: type: string nullable: true required: - id - legal_name - dba DealOwnerSummaryDto: type: object properties: first_name: type: string nullable: true last_name: type: string nullable: true email: type: string nullable: true phone: type: string nullable: true required: - first_name - last_name - email - phone DealPrimaryOfferDto: type: object properties: id: type: string description: Offer id. lender_id: type: string nullable: true lender_name: type: string nullable: true amount: type: number nullable: true description: Offered amount in dollars. factor_rate: type: number nullable: true status: type: string nullable: true description: >- Offer status slug, e.g. `new_offer`, `sold`, `contracts_out`, `funded`. required: - id - lender_id - lender_name - amount - factor_rate - status DealUserDto: type: object properties: id: type: string description: User id. name: type: string description: Display name. required: - id - name securitySchemes: bearer: scheme: bearer bearerFormat: API key or JWT type: http description: API key (`nlmca_live_…`) or OAuth access token ```` ## Related topics - [MCP server](/mcp/overview.md) - [Overview](/getting-started/overview.md) - [Update an offer](/api-reference/offers/update-an-offer.md)