> ## 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. # Update a deal > Partial update of deal fields. `form_data` is a JSON merge-patch: nested objects merge, `null` deletes a key, arrays and scalars replace. Setting `paper_grade` marks it as a manual override. Stage changes go through `POST /v1/deals/{id}/stage`. ## OpenAPI ````yaml /openapi/public-v1.json patch /v1/deals/{id} 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/{id}: patch: tags: - Deals summary: Update a deal description: >- Partial update of deal fields. `form_data` is a JSON merge-patch: nested objects merge, `null` deletes a key, arrays and scalars replace. Setting `paper_grade` marks it as a manual override. Stage changes go through `POST /v1/deals/{id}/stage`. operationId: deals_update parameters: - name: id required: true in: path description: Deal id schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/DealUpdateDto' responses: '200': description: OK content: application/json: schema: type: object required: - data - meta properties: data: $ref: '#/components/schemas/DealDto' 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' '429': description: Rate limit exceeded. See `X-RateLimit-*` and `Retry-After`. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelopeDto' security: - bearer: [] components: schemas: DealUpdateDto: type: object properties: requested_amount: type: number minimum: 0 description: Requested funding amount in dollars. use_of_funds: type: string maxLength: 2000 annual_revenue: type: number minimum: 0 description: Stated annual revenue in dollars. product_type: type: string enum: - mca - term_loan - loc - equipment - factoring - reverse_consolidation desired_term_months: type: number minimum: 1 maximum: 120 desired_frequency: type: string enum: - daily - weekly - bi-weekly - monthly paper_grade: type: string maxLength: 10 description: >- Paper grade override (`A`–`D`); marks `paper_grade_source` as `manual`. originator_id: type: string description: Originator (user id, from `GET /v1/users`). originator_email: type: string description: >- Originator by email, instead of `originator_id`. Must be an active team member. closer_id: type: string description: Closer (user id, from `GET /v1/users`). closer_email: type: string description: >- Closer by email, instead of `closer_id`. Must be an active team member. lead_source: type: string maxLength: 100 state_incorporated: type: string maxLength: 50 risk_flags: type: object description: Replaces the whole `risk_flags` object. form_data: type: object description: >- JSON merge-patch (RFC 7396) onto the deal’s `form_data`: nested objects merge key by key, a `null` value deletes the key, arrays and scalars replace. business_name: type: string maxLength: 255 description: >- Legal business name on this deal. When the deal showed its business’s legal name, the business is renamed too, and its other deals that showed the old name follow. A name the merchant typed differently changes on this deal only. dba: type: string maxLength: 255 description: >- DBA on this deal. When the deal showed its business’s DBA (or the business has none), the business takes it too, and its other deals that showed the old DBA follow. Otherwise it changes on this deal only. industry: type: string maxLength: 100 entity_type: type: string maxLength: 50 business_address: type: string business_city: type: string maxLength: 100 business_state: type: string maxLength: 50 business_zip: type: string maxLength: 20 business_phone: type: string maxLength: 50 business_start_date: type: string description: '`YYYY-MM-DD`.' 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 - reverse_consolidation 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 EmptyMetaDto: type: object properties: {} ErrorEnvelopeDto: type: object properties: error: $ref: '#/components/schemas/PublicErrorDto' required: - error 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 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 - documents_missing - documents_received description: System event bound to this stage, when it is event-driven. required: - id - label - phase - sort_order - event 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 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.