# JPMC-PDP Documentation from https://developer.payments.jpmorgan.com # Upload documents This guide walks you through the complete process of verifying, retrieving, uploading, and submitting document requests during client onboarding. 1. [Verify if a document is requested](/docs/embedded-finance-solutions/embedded-payments/capabilities/onboard-a-client/how-to/upload-documents#verify-if-a-document-is-requested) 2. [Identify and display the requested documents](/docs/embedded-finance-solutions/embedded-payments/capabilities/onboard-a-client/how-to/upload-documents#identify-and-display-requested-documents) 3. [Upload requested documents](/docs/embedded-finance-solutions/embedded-payments/capabilities/onboard-a-client/how-to/upload-documents#upload-requested-documents) 4. [Submit the uploaded documents for review](/docs/embedded-finance-solutions/embedded-payments/capabilities/onboard-a-client/how-to/upload-documents#submit-uploaded-documents-for-review) 5. [Verify document request submission](/docs/embedded-finance-solutions/embedded-payments/capabilities/onboard-a-client/how-to/upload-documents#verify-document-request-submission) ## Verify if a document is requested During the onboarding verification process, you may need to provide additional documents (for example, proof of identity) on behalf of your clients. This guide outlines the steps to upload and submit these documents. Documents may be requested at both client and party level in the onboarding process. - GET /clients/{id}: In the response, verify the outstanding.documentRequestIds field. - GET /parties/{id}: In the response, verify the validationResponse.documentRequestIds field. If documents are requested, the client's status changes from Review in Progress to Information Requested. #### Sample response indicating document requirements The following response shows that a client must provide documents using the `documentRequestId` 87975. ```json { "id": "{clientId}", "outstanding": { "documentRequestIds": [ "87975" ] } } ``` The following response shows that a party must provide documents that correspond to the `documentRequestId` 87991. ```json { "id": "{partyId}", "validationResponse": [ { "validationType": "ENTITY_VALIDATION", "validationStatus": "NEEDS_INFO", "documentRequestIds": [ "87991" ] } ] } ``` ### Notification If you subscribe to onboarding notifications, you will receive a notification when additional information or documents are requested. ```json { "eventId":"905", "eventType":"CLIENT_ONBOARDING", "resourceType":"CLIENTS", "resource":"{\"id\":\"3000005555\",\"status\":\"INFORMATION_REQUESTED\",\"hasOutstandingInformation\":true,\"customerIdentityStatus\":\"INFORMATION_REQUESTED\"}" } ``` > The `documentRequestId` is used as the identifier for all documents required in the request. For example, the ID 87975 may contain a request for multiple documents and types, such as a passport and a utility bill. > ## Identify and display requested documents To view what types of documents are required, send a request to `GET /document-requests/{documentRequestId}` using the document ID from `documentRequestIds`. ```curl curl --request GET \ --url https://api-mock.payments.jpmorgan.com/onboarding/v1/document-requests/87975 \ --header 'Accept: application/json' ``` ```json { "clientId": "3002034709", "createdAt": "2025-06-20T13:25:15.08Z", "id": "87975", "description": "To verify your identity, please provide any one of the below unexpired document which has Full Legal name, Address and Date of Birth.\n1. Drivers license\n2. Passport\n3. Government issued identity card\nIf address on your identification document is not current or present, please additionally provide a Utility Bill or Bank Statement dated within last 6 months.", "outstanding": { "documentTypes": [ "GOV_ISSUED_ID_CARD", "BANK_STATEMENT", "PASSPORT", "DRIVERS_LICENSE", "UTILITY_BILL" ] }, "requirements": [ { "documentTypes": [ "PASSPORT", "DRIVERS_LICENSE", "GOV_ISSUED_ID_CARD" ], "minRequired": 1 }, { "documentTypes": [ "UTILITY_BILL", "BANK_STATEMENT" ], "minRequired": 0 } ], "status": "ACTIVE", "validForDays": 5 } ``` ### Details included in a sample response A sample response includes the following information about the requested documents for a client or a party: - Description: A description of the requested documents. Display this text exactly as it is written to your end user. New lines are indicated with "\n". - Requirements: A list of required documents. - Document types: A list of accepted document types for each requested document. For example, a passport or a utility bill. - Minimum required: The minimum number of documents required for the requested documents. For example, a party might be required to provide a passport or driving license and a utility bill, giving a minRequired count of two. - Outstanding: A list of missing document types. - Outstanding document types: A list of all the document types that are required but have not yet been uploaded. ### Get all document requests for a client To retrieve all document requests associated with a client, use the `GET /document-requests?clientId={clientId}` endpoint. This call returns all open document requests tied to a client. ```curl curl --request GET \ --url https://api-mock.payments.jpmorgan.com/onboarding/v1/document-requests?clientId=3002034709 \ --header 'Accept: application/json' ``` ```json { "documentRequests": [ { "clientId": "3002034709", "createdAt": "2025-06-20T13:25:15.08Z", "id": "87975", "description": "To verify your identity, please provide any one of the below unexpired document which has Full Legal name, Address and Date of Birth.\n1. Drivers license\n2. Passport\n3. Government issued identity card\nIf address on your identification document is not current or present, please additionally provide a Utility Bill or Bank Statement dated within last 6 months.", "outstanding": { "documentTypes": [ "BANK_STATEMENT", "UTILITY_BILL", "DRIVERS_LICENSE", "PASSPORT", "GOV_ISSUED_ID_CARD" ] }, "requirements": [ { "documentTypes": [ "PASSPORT", "DRIVERS_LICENSE", "GOV_ISSUED_ID_CARD" ], "minRequired": 1 }, { "documentTypes": [ "UTILITY_BILL", "BANK_STATEMENT" ], "minRequired": 0 } ], "status": "ACTIVE", "validForDays": 5 } ], "metadata": { "page": 0, "limit": 25, "total": 1 } } ``` ## Upload requested documents To upload a requested document, use the `POST /documents` endpoint. When uploading a document specify the following: - The documentRequestId for upload in the documentData.documentRequestId field. - The documentType for upload in the documentData.documentType field. - Attach a file as multipart/form-data. - Attach a document metadata as a JSON string in the documentData field. Example: documentData={"documentType": {documentType},"documentRequestId":{documentRequestId}}. Supported file types: - PNG - JPEG - PDF - Max file size: 2MB. Next, the user uploads a document with a type of Drivers License. The document content is sent as a file in the file field, and the document metadata is sent in the `documentData` field. ```curl curl --request POST --url 'https://api-mock.payments.jpmorgan.com/onboarding/v1/documents' \ --form 'file=@"driverLicenseFront.pdf"' \ --form 'documentData="{\"documentType\": \"DRIVERS_LICENSE\",\"documentRequestId\":\"87975\"}"' ``` ```json { "id": "fd05afd7-edcd-456f-8480-2aa25883274b", "documentType": "DRIVERS_LICENSE", "metadata": [ { "key": "DOCUMENT_REQUEST_ID", "value": "87975" }, { "key": "FILE_EXTENSION", "value": "pdf" }, { "key": "UPLOAD_TIME", "value": "2025-06-20T13:25:15.080Z" }, { "key": "STATUS", "value": "NEW" }, { "key": "UPLOADED_FILE_NAME", "value": "driverLicenseFront.pdf" } ] } ``` After the required document is uploaded, it is removed from the outstanding.`documentTypes` list, and the corresponding required object is removed from outstanding.`requirements`. This happens because the minimum number of document types for that requirement is one, so uploading a single acceptable document fulfills the requirement. As long as at least one document is uploaded with one of the requested types, the `requirements` field remains unchanged. The response payload reflects that the outstanding.`documentTypes` and outstanding.`requirements` are now empty, indicating that nothing is outstanding. ```curl curl --location 'https://api-mock.payments.jpmorgan.com/onboarding/v1/document-requests/87975' ``` ```json { "clientId": "3002034709", "createdAt": "2025-06-20T13:25:15.08Z", "id": "87975", "description": "To verify your identity, please provide any one of the below unexpired document which has Full Legal name, Address and Date of Birth.\n1. Drivers license\n2. Passport\n3. Government issued identity card\nIf address on your identification document is not current or present, please additionally provide a Utility Bill or Bank Statement dated within last 6 months.", "outstanding": { "documentTypes": [] }, "requirements": [ { "documentTypes": [ "PASSPORT", "DRIVERS_LICENSE", "GOV_ISSUED_ID_CARD" ], "minRequired": 1 }, { "documentTypes": [ "UTILITY_BILL", "BANK_STATEMENT" ], "minRequired": 0 } ], "status": "ACTIVE", "validForDays": 5 } ``` The document request status remains ACTIVE. Users can continue uploading documents, either of the same type or different types, as long as they fulfill the requirements specified in the document request. ### Upload multiple files for a single document type Upload each file separately with `POST /documents`. For each document upload, specify the same document type and request ID. ```json curl --request POST --url 'https://api-mock.payments.jpmorgan.com/onboarding/v1/documents' \ --form 'file=@"driverLicenseBack.pdf"' \ --form 'documentData="{\"documentType\": \"DRIVERS_LICENSE\",\"documentRequestId\":\"87975\"}"' ``` ```json { "id": "96846c4a-c8ef-4f12-be20-33654899b2da", "documentType": "DRIVERS_LICENSE", "metadata": [ { "key": "DOCUMENT_REQUEST_ID", "value": "87975" }, { "key": "FILE_EXTENSION", "value": "pdf" }, { "key": "UPLOAD_TIME", "value": "2025-06-20T13:25:15.080Z" }, { "key": "STATUS", "value": "NEW" }, { "key": "UPLOADED_FILE_NAME", "value": "driverLicenseBack.pdf" } ] } ``` ### Upload multiple document types for one document request Upload multiple document types for one document request with `POST /documents`. Specify the applicable document type and document request ID in each document upload. ```json curl --request POST --url 'https://api-mock.payments.jpmorgan.com/onboarding/v1/documents' \ --form 'file=@"govIssuedIdCard.pdf"' \ --form 'documentData="{\"documentType\":\"GOV_ISSUED_ID_CARD\",\"documentRequestId\":\"87975\"}"' ``` ```json { "id": "07f349a0-10f8-4502-94f2-4dbda15abfa8", "documentType": "GOV_ISSUED_ID_CARD", "metadata": [ { "key": "DOCUMENT_REQUEST_ID", "value": "87975" }, { "key": "FILE_EXTENSION", "value": "pdf" }, { "key": "UPLOAD_TIME", "value": "2025-06-20T13:25:15.080Z" }, { "key": "STATUS", "value": "NEW" }, { "key": "UPLOADED_FILE_NAME", "value": "govIssuedIdCard.pdf" } ] } ``` ### Verify uploaded documents To verify uploaded documents, use the `GET /documents?clientId={clientId}` endpoint. The response will include all documents uploaded for the client, including those tied to a document request. ```curl curl --location 'https://api-mock.payments.jpmorgan.com/onboarding/v1/documents?clientId=3002034709' ``` Sample response with all documents uploaded for a client: ```json { "metadata": { "page": 0, "limit": 25, "total": 3 }, "documentDetails": [ { "id": "07f349a0-10f8-4502-94f2-4dbda15abfa8", "documentType": "GOV_ISSUED_ID_CARD", "metadata": [ { "key": "DOCUMENT_REQUEST_ID", "value": "87975" }, { "key": "FILE_EXTENSION", "value": "pdf" }, { "key": "UPLOAD_TIME", "value": "1750427631941" }, { "key": "STATUS", "value": "NEW" }, { "key": "UPLOADED_FILE_NAME", "value": "govIssuedIdCard.pdf" } ] }, { "id": "96846c4a-c8ef-4f12-be20-33654899b2da", "documentType": "DRIVERS_LICENSE", "metadata": [ { "key": "DOCUMENT_REQUEST_ID", "value": "87975" }, { "key": "FILE_EXTENSION", "value": "pdf" }, { "key": "UPLOAD_TIME", "value": "1750428037857" }, { "key": "STATUS", "value": "NEW" }, { "key": "UPLOADED_FILE_NAME", "value": "driverLicenseBack.pdf" } ] }, { "id": "fd05afd7-edcd-456f-8480-2aa25883274b", "documentType": "DRIVERS_LICENSE", "metadata": [ { "key": "DOCUMENT_REQUEST_ID", "value": "87975" }, { "key": "FILE_EXTENSION", "value": "pdf" }, { "key": "UPLOAD_TIME", "value": "1750427356661" }, { "key": "STATUS", "value": "NEW" }, { "key": "UPLOADED_FILE_NAME", "value": "driverLicenseFront.pdf" } ] } ] } ``` ### Download uploaded documents To download an uploaded document, use the `GET /documents/{id}/file` endpoint. `{id}` represent the ID of the document you want to download. ```curl curl --location 'https://api-mock.payments.jpmorgan.com/onboarding/v1/documents/07f349a0-10f8-4502-94f2-4dbda15abfa8/file' ``` ## Submit uploaded documents for review To submit the uploaded documents for review, use the `POST /v1/document-requests/{documentRequestId}/submit`. Sample request to submit the document request: ```curl curl --location --request POST 'https://api-mock.payments.jpmorgan.com/onboarding/v1/document-requests/87975/submit' ``` After the document is successfully submitted, the response returns a 202 Accepted status along with the acceptance timestamp. ```json Response 202 { "acceptedAt": "2025-06-20T14:23:37.490076812Z" } ``` ## Verify document request submission To verify that the document request has been submitted, use the `GET /document-requests/{id}` endpoint. After submission, the status changes from ACTIVE to CLOSED. ```curl curl --location 'https://api-mock.payments.jpmorgan.com/onboarding/v1/document-requests/87975' ``` ```json { "clientId": "3002034709", "createdAt": "2025-06-20T13:25:15.08Z", "id": "87975", "description": "To verify your identity, please provide any one of the below unexpired document which has Full Legal name, Address and Date of Birth.\n1. Drivers license\n2. Passport\n3. Government issued identity card\nIf address on your identification document is not current or present, please additionally provide a Utility Bill or Bank Statement dated within last 6 months.", "outstanding": { "documentTypes": [] }, "requirements": [ { "documentTypes": [ "PASSPORT", "DRIVERS_LICENSE", "GOV_ISSUED_ID_CARD" ], "minRequired": 1 }, { "documentTypes": [ "UTILITY_BILL", "BANK_STATEMENT" ], "minRequired": 0 } ], "status": "CLOSED", "validForDays": 5 } ``` ## Handling errors for outstanding requirements In case there are outstanding document types, your request returns a 400 Bad Request response. To resolve the error, do the following: 1. Use the GET /document-requests/{id} endpoint to verify outstanding documents. 2. Upload additional documents using POST /documents. 3. Re-submit using POST /v1/document-requests/{documentRequestId}/submit. ## Confirm completion To verify client status again, use the GET /client/{id}` endpoint. The status should change from Information Requested to Review in Progress if all documents were accepted. ## Example flow for US corporations The following example illustrates the complete document upload and submission process for a corporation: 1. The user views a document request using a partyId. 2. The response includes upload instructions and which document types are accepted. 3. The user uploads the required documents. 4. That document type is removed from outstanding.documentTypes and the requirements are fulfilled. 5. The document request remains active until submission. 6. Once submitted the status changes to closed. 7. No more documents can be uploaded after submission. ```json { "createdAt": "2025-06-20T14:42:02.079Z", "id": "87991", "partyId": "2001197261", "description": "To verify your identity, please provide requested documents.\n1. Formation Document - Listing the legal name and address of the company. Acceptable documents are Articles of Incorporation [OR] Certificate of Good Standing [OR] Certificate of Incumbency [OR] Memorandum/Articles of Association [OR] Constitutional document [OR] LLC Agreement [OR] Filing receipt from state of organization [OR] Operating Agreement.", "outstanding": { "documentTypes": [ "ARTICLES_OF_ASSOCIATION", "CONSTITUTIONAL_DOCUMENT", "ARTICLES_OF_INCORPORATION", "LLC_AGREEMENT", "OPERATING_AGREEMENT", "FILING_RECEIPT", "INCUMBENCY_CERTIFICATE", "CERTIFICATE_OF_GOOD_STANDING" ] }, "requirements": [ { "documentTypes": [ "ARTICLES_OF_INCORPORATION", "CERTIFICATE_OF_GOOD_STANDING", "INCUMBENCY_CERTIFICATE", "ARTICLES_OF_ASSOCIATION", "CONSTITUTIONAL_DOCUMENT", "LLC_AGREEMENT", "FILING_RECEIPT", "OPERATING_AGREEMENT" ], "level": "PRIMARY", "minRequired": 1 } ], "status": "ACTIVE", "validForDays": 5 } ``` Next, the user uploads a document with a type of Article of incorporation. Sample upload request: ```curl curl --location 'https://api-mock.payments.jpmorgan.com/onboarding/v1/documents' \ --form 'file=@"articleOfIncorporation.pdf"' \ --form 'documentData="{\"documentType\":\"ARTICLES_OF_INCORPORATION\",\"documentRequestId\":\"87991\"}"' ``` ```json { "id": "a5002ca8-6b1f-4728-800d-53cff0320d4a", "documentType": "ARTICLES_OF_INCORPORATION", "metadata": [ { "key": "DOCUMENT_REQUEST_ID", "value": "87991" }, { "key": "FILE_EXTENSION", "value": "pdf" }, { "key": "UPLOAD_TIME", "value": "2025-06-20T14:42:02.079Z" }, { "key": "STATUS", "value": "NEW" }, { "key": "UPLOADED_FILE_NAME", "value": "articleOfIncorporation.pdf" } ] } ``` When an Article of Incorporation document is uploaded, it is removed from outstanding.`documentTypes`. Additionally, the first requirement object is completely removed from outstanding.`requirements`. This occurs because the minimum required document types for that requirement was one, meaning the requirement is fulfilled as long as at least one document of the requested type is uploaded. The `requirements` field itself remains unchanged, and the response payload confirms that it has not been altered following the document upload. ```curl curl --location 'https://api-mock.payments.jpmorgan.co/onboarding/v1/document-requests/87991' ``` There is now nothing outstanding, as shown by the empty outstanding.`documentTypes` and outstanding.`requirements`. ```json { "createdAt": "2025-06-20T14:42:02.079Z", "id": "87991", "partyId": "2001197261", "description": "To verify your identity, please provide requested documents.\n1. Formation Document - Listing the legal name and address of the company. Acceptable documents are Articles of Incorporation [OR] Certificate of Good Standing [OR] Certificate of Incumbency [OR] Memorandum/Articles of Association [OR] Constitutional document [OR] LLC Agreement [OR] Filing receipt from state of organization [OR] Operating Agreement.", "outstanding": { "documentTypes": [] }, "requirements": [ { "documentTypes": [ "ARTICLES_OF_INCORPORATION", "CERTIFICATE_OF_GOOD_STANDING", "INCUMBENCY_CERTIFICATE", "ARTICLES_OF_ASSOCIATION", "CONSTITUTIONAL_DOCUMENT", "LLC_AGREEMENT", "FILING_RECEIPT", "OPERATING_AGREEMENT" ], "level": "PRIMARY", "minRequired": 1 } ], "status": "ACTIVE", "validForDays": 5 } ``` The document request status remains active. Users can upload any remaining documents they want as long as they are within the specified requirements. ```json Response 202 { "acceptedAt": "2025-06-20T14:49:09.857748688Z" } ``` To confirm that the document request is complete, send a request to retrieve the document status. If the status is now Closed, the document request is now completed. Users can no longer upload documents for this request after it has been submitted. ```json "createdAt": "2025-06-20T14:42:02.079Z", "id": "87991", "partyId": "2001197261", "description": "To verify your identity, please provide requested documents.\n1. Formation Document - Listing the legal name and address of the company. Acceptable documents are Articles of Incorporation [OR] Certificate of Good Standing [OR] Certificate of Incumbency [OR] Memorandum/Articles of Association [OR] Constitutional document [OR] LLC Agreement [OR] Filing receipt from state of organization [OR] Operating Agreement.", "outstanding": { "documentTypes": [] }, "requirements": [ { "documentTypes": [ "ARTICLES_OF_INCORPORATION", "CERTIFICATE_OF_GOOD_STANDING", "INCUMBENCY_CERTIFICATE", "ARTICLES_OF_ASSOCIATION", "CONSTITUTIONAL_DOCUMENT", "LLC_AGREEMENT", "FILING_RECEIPT", "OPERATING_AGREEMENT" ], "level": "PRIMARY", "minRequired": 1 } ], "status": "CLOSED", "validForDays": 5 } ```