> ## 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. # Request documents from the merchant > Creates a document request (tracked in the app) and a merchant-portal upload link. `channel: "email"` emails it through the location’s connected mailbox (409 `no_email_sender` when none is connected); `"sms"` texts it through the CRM conversation when the contact is linked to the CRM — otherwise the link is returned with `sent: false` and `meta.warning`; `"link_only"` never sends. Uploads through the link are matched to the requested items automatically. Send an `Idempotency-Key` to avoid duplicate requests on retry. ## OpenAPI ````yaml /openapi/public-v1.json post /v1/deals/{dealId}/document-requests 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/{dealId}/document-requests: post: tags: - Documents summary: Request documents from the merchant description: >- Creates a document request (tracked in the app) and a merchant-portal upload link. `channel: "email"` emails it through the location’s connected mailbox (409 `no_email_sender` when none is connected); `"sms"` texts it through the CRM conversation when the contact is linked to the CRM — otherwise the link is returned with `sent: false` and `meta.warning`; `"link_only"` never sends. Uploads through the link are matched to the requested items automatically. Send an `Idempotency-Key` to avoid duplicate requests on retry. operationId: documents_createRequest parameters: - name: dealId required: true in: path description: Deal id schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateDocumentRequestDto' responses: '201': description: Created content: application/json: schema: type: object required: - data - meta properties: data: $ref: '#/components/schemas/DocumentRequestDto' 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: CreateDocumentRequestDto: type: object properties: items: description: Documents to request. At least one. type: array items: $ref: '#/components/schemas/DocumentRequestItemInputDto' channel: type: string enum: - email - sms - link_only description: >- `email` sends through the location’s connected mailbox (409 `no_email_sender` if none is connected); `sms` texts the upload link through the CRM conversation when the contact is linked to the CRM, otherwise the link is returned unsent; `link_only` never sends — you deliver the link yourself. person_id: type: string description: >- Person to send to. Defaults to the deal’s primary owner, then the business’s primary contact. message: type: string description: Note included in the email or text. maxLength: 2000 expires_in_days: type: number description: Days until the request expires (1–90). Default 30. minimum: 1 maximum: 90 required: - items - channel DocumentRequestDto: type: object properties: id: type: string description: Document request id. deal_id: type: string description: Deal the request belongs to. status: type: string enum: - pending - partial - complete - expired description: Overall state. `partial` = some items received. channel: type: string enum: - email - sms - link_only description: Channel that was requested. delivery: type: string enum: - email - sms - link_only description: >- How the link was actually delivered. `link_only` when nothing was sent (see `meta.warning`). sent: type: boolean description: True when an email or text went out. sent_to: type: string nullable: true description: Masked email or phone the link was sent to. upload_url: type: string description: >- Merchant upload link (merchant portal). Valid 24 hours; the portal lets the merchant request a fresh one. expires_at: type: string nullable: true description: When the request expires (ISO 8601). items: description: Requested items. type: array items: $ref: '#/components/schemas/DocumentRequestItemDto' created_at: type: string description: Creation time (ISO 8601). required: - id - deal_id - status - channel - delivery - sent - sent_to - upload_url - expires_at - items - created_at EmptyMetaDto: type: object properties: {} ErrorEnvelopeDto: type: object properties: error: $ref: '#/components/schemas/PublicErrorDto' required: - error DocumentRequestItemInputDto: type: object properties: type: type: string enum: - bank_statement - voided_check - drivers_license - business_license - tax_returns - proof_of_ownership - utility_bill description: What to ask the merchant for. label: type: string description: >- Label shown to the merchant instead of the default one, e.g. `Last 4 months of statements`. maxLength: 255 required: - type DocumentRequestItemDto: type: object properties: id: type: string description: Request item id. type: type: string description: Requested type, e.g. `bank_statement`. label: type: string description: Label shown to the merchant. status: type: string enum: - pending - received - rejected description: Fulfilment state of this item. received_document_id: type: string nullable: true description: Document that satisfied the item, once received. received_at: type: string nullable: true description: When the document was received (ISO 8601). required: - id - type - label - status - received_document_id - received_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 securitySchemes: bearer: scheme: bearer bearerFormat: API key or JWT type: http description: API key (`nlmca_live_…`) or OAuth access token ```` ## Related topics - [Documents and uploads](/guides/documents-and-uploads.md) - [Get a document](/api-reference/documents/get-a-document.md) - [Create or send a merchant portal link](/api-reference/merchant-portal/create-or-send-a-merchant-portal-link.md)