Upload Document
POST /applications/{application}/documents
Environment and operation
Use this endpoint contract with the account and environment assigned to your integration. Values in angle brackets are placeholders. This reference does not execute requests. Documented server https://sandbox.signup.nmi.com/api/v1 https://secure.nmi.com/api/v5/signup Schema reference: field definitions do not include every behavioral rule. Follow the workflow guidance and account prerequisites for this operation before submitting requests.
Request route
Provide supporting documents for the application. Documents can only be uploaded while the application is the `draft` or `underwriter_requested_information` status. **Required scope:** `applications:write` POST /applications/{application}/documents Security scheme Type Credential location Scopes oauth oauth2 applications:write
Request language templates
Original transport templates derived from this endpoint’s documented method, server, authentication and media type. Replace path/query/credential placeholders with authorized sandbox values. These examples print the raw status and response; they do not infer business success or retry a request. This example uploads document.pdf as the published Void Check variant. Use an authorized sandbox application and a test document. The client generates the multipart boundary; do not set Content-Type manually. Python requires requests. Node requires a runtime with fetch; PHP requires cURL. Generated source-based examples have not been executed against provider accounts. curl --request POST \ --url 'https://sandbox.signup.nmi.com/api/v1/applications/{application}/documents' \ --header 'Authorization: Bearer <access-token>' \ --form 'type=Void Check' \ --form 'file=@document.pdf;type=application/pdf' import { readFile } from 'node:fs/promises'; const body = new FormData(); body.set('type', 'Void Check'); body.set('file', new Blob([await readFile('document.pdf')], { type: 'application/pdf' }), 'document.pdf'); const response = await fetch("https://sandbox.signup.nmi.com/api/v1/applications/{application}/documents", { method: 'POST', headers: { "Authorization": "Bearer <access-token>" }, body }); console.log(response.status, await response.text()); # Requires the requests package. import requests with open('document.pdf', 'rb') as document: response = requests.request('POST', 'https://sandbox.signup.nmi.com/api/v1/applications/{application}/documents', headers={'Authorization': 'Bearer <access-token>'}, data={'type': 'Void Check'}, files={'file': ('document.pdf', document, 'application/pdf')}, timeout=30) print(response.status_code, response.text) require 'net/http' require 'uri' uri = URI("https://sandbox.signup.nmi.com/api/v1/applications/{application}/documents") request = Net::HTTP::Post.new(uri) request["Authorization"] = "Bearer <access-token>" document = File.open('document.pdf', 'rb') request.set_form([['type', 'Void Check'], ['file', document, { filename: 'document.pdf', content_type: 'application/pdf' }]], 'multipart/form-data') response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https', read_timeout: 30) { |http| http.request(request) } puts response.code puts response.body document.close <?php $curl = curl_init('https://sandbox.signup.nmi.com/api/v1/applications/{application}/documents'); curl_setopt_array($curl, [ CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 30, CURLOPT_HTTPHEADER => ['Authorization: Bearer <access-token>'], CURLOPT_POSTFIELDS => ['type' => 'Void Check', 'file' => new CURLFile('document.pdf', 'application/pdf', 'document.pdf')] ]); $response = curl_exec($curl); if ($response === false) { throw new RuntimeException(curl_error($curl)); } echo curl_getinfo($curl, CURLINFO_HTTP_CODE), PHP_EOL, $response; curl_close($curl);
Path and query parameters
Required flags apply to the parameter itself. Additional limits and enum values appear in the contract below. Parameter Location Required Type Description Idempotency-Key header false string Provide a random key (for example, UUID) to make the request idempotent application path true See schema The ID of the application to provide document [ { "name": "Idempotency-Key", "in": "header", "description": "Provide a random key (for example, UUID) to make the request idempotent", "schema": { "type": "string", "minLength": 10, "maxLength": 100 }, "required": false }, { "name": "application", "in": "path", "description": "The ID of the application to provide document", "required": true, "schema": { "$ref": "#/components/schemas/application-id" } } ] true
Request body
Use the declared media type: multipart/form-data. Required flags below apply within the selected object or variant. Read the workflow notes before choosing a variant. Field Type Required Description Constraints type string yes The type of the document enum: ["Void Check", "Marketing Materials", "3 Months of Statements", "Driver License", "SSN Card", "Form SS4", "Other"] file string yes The document to upload (accepted formats: image/png, image/jpg, image/jpeg, application/pdf, max filesize 20 MB) maxLength: 20971520; format: "binary" { "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "type", "file" ], "properties": { "type": { "$ref": "#/components/schemas/application-document-type" }, "file": { "type": "string", "description": "The document to upload (accepted formats: image/png, image/jpg, image/jpeg, application/pdf, max filesize 20 MB)", "format": "binary", "maxLength": 20971520 } } }, "examples": { "upload-void-check": { "summary": "Upload void check document", "description": "Upload void check document for an application", "value": { "type": "Void Check", "file": "[binary file content]" } } } } }, "required": true } true
Responses
Match the HTTP status to its response schema below. For financial operations, also inspect the payment outcome before updating your order or retrying. HTTP status Media type Meaning 200 application/json Document uploaded successfully 404 application/json Error response for resource not found 422 application/json Validation error { "200": { "description": "Document uploaded successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/application-document" }, "examples": { "success": { "$ref": "#/components/examples/sample-document-void-check" } } } } }, "404": { "description": "Error response for resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Error code", "maxLength": 100 }, "message": { "type": "string", "description": "Error message", "maxLength": 10000 } } }, "examples": { "not-found": { "summary": "Resource Not Found", "description": "The resource cannot be found", "value": { "code": "NOT_FOUND", "message": "Resource not found" } } } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/validation-error" }, "examples": { "sample-error": { "summary": "Invalid Request", "description": "Error when attempting to upload invalid file type", "value": { "code": "VALIDATION_ERROR", "message": "The file field must be a file of type: pdf, jpg, jpeg, png.", "errors": [ "The file field must be a file of type: pdf, jpg, jpeg, png." ] } } } } } } } true
Response fields · 200 · application/json
Field Type Required Description Constraints id string yes The unique identifier of the document. minLength: 20; maxLength: 20; pattern: "^doc_[a-f0-9]{16}$" application_id string yes The unique identifier of the application. minLength: 20; maxLength: 20; pattern: "^app_[a-f0-9]{16}$" type string yes The type of the document enum: ["Void Check", "Marketing Materials", "3 Months of Statements", "Driver License", "SSN Card", "Form SS4", "Other"] file_name string yes maxLength: 255 status string yes The status of the document enum: ["draft", "submitted"] created_at string yes The date and time when was created. maxLength: 32; format: "date-time" updated_at string yes The date and time when was last updated. maxLength: 32; format: "date-time"
Response fields · 404 · application/json
Field Type Required Description Constraints code string no Error code maxLength: 100 message string no Error message maxLength: 10000
Response fields · 422 · application/json
Field Type Required Description Constraints code string no Error code maxLength: 1000 message string no Error message maxLength: 1000 errors array no
Referenced schema definitions
References beginning with #/components resolve to these definitions. These are field contracts, not example payment values. Use the applicable variant, required fields and constraints. { "securitySchemes": { "oauth": { "type": "oauth2", "flows": { "clientCredentials": { "tokenUrl": "/oauth/token", "scopes": { "*": "Full access", "packages:read": "Read packages information", "applications:read": "Read access to applications", "applications:write": "Write access to applications", "subscriptions:read": "Read access to subscriptions", "subscriptions:write": "Write access to subscriptions (subscribe/updated/delete)" } } } } }, "schemas": { "application-id": { "type": "string", "description": "The unique identifier of the application.", "pattern": "^app_[a-f0-9]{16}$", "minLength": 20, "maxLength": 20 }, "validation-error": { "type": "object", "properties": { "code": { "type": "string", "description": "Error code", "maxLength": 1000 }, "message": { "type": "string", "description": "Error message", "maxLength": 1000 }, "errors": { "type": "array", "maxItems": 10, "items": { "type": "string", "description": "The error message", "maxLength": 1000 } } } }, "application-document-type": { "type": "string", "description": "The type of the document", "enum": [ "Void Check", "Marketing Materials", "3 Months of Statements", "Driver License", "SSN Card", "Form SS4", "Other" ] }, "application-document-status": { "type": "string", "description": "The status of the document", "enum": [ "draft", "submitted" ] }, "datetime-created-at": { "type": "string", "description": "The date and time when was created.\n", "format": "date-time", "maxLength": 32, "example": "2025-01-01T00:00:00Z" }, "datetime-updated-at": { "type": "string", "description": "The date and time when was last updated.\n", "format": "date-time", "maxLength": 32, "example": "2025-01-01T00:00:00Z" }, "application-document": { "type": "object", "description": "Application document info.\n", "required": [ "id", "application_id", "type", "file_name", "status", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "description": "The unique identifier of the document.", "pattern": "^doc_[a-f0-9]{16}$", "minLength": 20, "maxLength": 20 }, "application_id": { "$ref": "#/components/schemas/application-id" }, "type": { "$ref": "#/components/schemas/application-document-type" }, "file_name": { "type": "string", "maxLength": 255 }, "status": { "$ref": "#/components/schemas/application-document-status" }, "created_at": { "$ref": "#/components/schemas/datetime-created-at" }, "updated_at": { "$ref": "#/components/schemas/datetime-updated-at" } } }, "event-types": { "type": "string", "enum": [ "application.updated.data.requested", "application.approved", "application.declined", "application.cancelled", "application.merchant.closed", "application.merchant.boarded", "merchant.chargeback.added", "merchant.deposit.new", "merchant.first-batch", "merchant.processing.start", "merchant.processing.stop", "merchant.residuals.published", "merchant.retrieval.added", "merchant.statement.new" ], "example": "application.merchant.boarded" } }, "responses": { "error-not-found": { "description": "Error response for resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Error code", "maxLength": 100 }, "message": { "type": "string", "description": "Error message", "maxLength": 10000 } } }, "examples": { "not-found": { "summary": "Resource Not Found", "description": "The resource cannot be found", "value": { "code": "NOT_FOUND", "message": "Resource not found" } } } } } } }, "examples": { "sample-document-void-check": { "summary": "Success", "description": "Sample document (void check) for application", "value": { "id": "doc_1b4254029faede5a", "application_id": "app_341c7b5b432a3158", "type": "Void Check", "file_name": "void_check.pdf", "status": "draft", "created_at": "2025-01-14T14:20:16+00:00", "updated_at": "2025-01-14T14:20:16+00:00" } } } } true
Integration checks
Validate the request against its selected schema before submission. Keep secrets outside browser code. Test permitted and denied account access, validation failures and interrupted responses in the sandbox. Account-management or messaging operations require the corresponding partner access and intended recipient context.