> ## 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. # Create a lender > Adds a lender to the location. Names are unique per location (409 `duplicate_lender`). Set eligibility rules afterwards with `PUT /lenders/{id}/criteria`. ## OpenAPI ````yaml /openapi/public-v1.json post /v1/lenders 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/lenders: post: tags: - Lenders summary: Create a lender description: >- Adds a lender to the location. Names are unique per location (409 `duplicate_lender`). Set eligibility rules afterwards with `PUT /lenders/{id}/criteria`. operationId: lenders_create parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateLenderDto' responses: '201': description: Created content: application/json: schema: type: object required: - data - meta properties: data: $ref: '#/components/schemas/LenderDto' 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' '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: CreateLenderDto: type: object properties: name: type: string description: >- Lender name. Must be unique within the location (409 `duplicate_lender`). maxLength: 255 status: type: string enum: - active - inactive default: active description: Inactive lenders are excluded from matching. paper_grades: type: array description: Paper grades the lender buys. items: type: string enum: - A - B - C - D tags: description: Free-form tags. type: array items: type: string products: description: 'Products the lender writes. Defaults to `{ mca: true }`.' allOf: - $ref: '#/components/schemas/LenderProductsDto' use_api: type: boolean description: >- True when submissions go through an API integration rather than email. contact_name: type: string description: Primary contact name at the lender. maxLength: 255 email: type: string description: Contact email. phone: type: string description: Contact phone. maxLength: 50 submissions_emails: description: >- Addresses deal submissions are emailed to. Required before the lender can receive submissions. type: array items: type: string payment_terms: type: string description: Commission payment terms, e.g. `Net 30`. maxLength: 255 clawback_period: type: number description: Clawback window length. minimum: 0 clawback_unit: type: string enum: - days - weeks - months description: Unit of `clawback_period`. default_commission: type: number description: Default commission percentage (0–100). minimum: 0 maximum: 100 notes: type: string description: Internal notes. maxLength: 5000 required: - name LenderDto: type: object properties: id: type: string description: Lender id. name: type: string description: Lender name (unique within the location). status: type: string enum: - active - inactive description: Inactive lenders are excluded from matching. paper_grades: type: array description: Paper grades the lender buys. items: type: string enum: - A - B - C - D tags: description: Free-form tags. type: array items: type: string products: description: Products the lender writes. Product is a hard gate in matching. allOf: - $ref: '#/components/schemas/LenderProductsDto' use_api: type: boolean description: >- True when submissions go through an API integration rather than email. contact_name: type: string nullable: true description: Primary contact name at the lender. email: type: string nullable: true description: Contact email. phone: type: string nullable: true description: Contact phone. submissions_emails: description: Addresses deal submissions are emailed to. type: array items: type: string payment_terms: type: string nullable: true description: Commission payment terms, e.g. `Net 30`. clawback_period: type: number nullable: true description: Clawback window length. clawback_unit: type: string nullable: true enum: - days - weeks - months description: Unit of `clawback_period`. default_commission: type: number nullable: true description: Default commission percentage (0–100). notes: type: string nullable: true description: Internal notes. criteria_count: type: number description: >- Number of criteria set (structured keys + extra rules). See `GET /lenders/{id}/criteria`. criteria_updated_at: type: string nullable: true description: When criteria were last changed (ISO 8601). kpis: description: Track record with this location (recomputed nightly and on demand). allOf: - $ref: '#/components/schemas/LenderKpisDto' created_at: type: string description: Creation time (ISO 8601). updated_at: type: string nullable: true description: Last update time (ISO 8601). required: - id - name - status - paper_grades - tags - products - use_api - contact_name - email - phone - submissions_emails - payment_terms - clawback_period - clawback_unit - default_commission - notes - criteria_count - criteria_updated_at - kpis - created_at - updated_at EmptyMetaDto: type: object properties: {} ErrorEnvelopeDto: type: object properties: error: $ref: '#/components/schemas/PublicErrorDto' required: - error LenderProductsDto: type: object properties: mca: type: boolean description: Writes merchant cash advances. term_loan: type: boolean description: Writes term loans. loc: type: boolean description: Writes lines of credit. equipment: type: boolean description: Writes equipment financing. factoring: type: boolean description: Writes invoice factoring. LenderKpisDto: type: object properties: submissions_count: type: number description: Submissions ever sent to this lender from this location. decided_count: type: number description: Submissions with a decision (approved, declined or funded). approved_count: type: number description: Approved or funded submissions. approval_rate: type: number nullable: true description: >- approved_count / decided_count as a percentage (0–100). Null with no decisions. avg_deal_size: type: number nullable: true description: Average funded amount across advances with this lender. total_funded: type: number description: Total funded through this lender. total_advances: type: number description: Number of advances funded by this lender. last_submission_at: type: string nullable: true description: Most recent submission (ISO 8601). required: - submissions_count - decided_count - approved_count - approval_rate - avg_deal_size - total_funded - total_advances - last_submission_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 - [Create a deal](/api-reference/deals/create-a-deal.md) - [Create a business](/api-reference/businesses/create-a-business.md) - [Authentication](/getting-started/authentication.md)