Skip to main content
Embedded Payments

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
  2. Identify and display the requested documents
  3. Upload requested documents
  4. Submit the uploaded documents for review
  5. 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.

Sample response showing that documents are required for a client
Json
{
  "id": "{clientId}",
  "outstanding": {
    "documentRequestIds": [
      "87975"
    ]
  }
}

The following response shows that a party must provide documents that correspond to the documentRequestId 87991.

Response showing that documents are requested for a party
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.

Client Status - INFORMATION_REQUESTED
Json
{
    "eventId":"905",
    "eventType":"CLIENT_ONBOARDING",
    "resourceType":"CLIENTS",
    "resource":"{\"id\":\"3000005555\",\"status\":\"INFORMATION_REQUESTED\",\"hasOutstandingInformation\":true,\"customerIdentityStatus\":\"INFORMATION_REQUESTED\"}"
}
Note

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.

Sample request to retrieve document details
Curl
curl --request GET \
--url https://api-mock.payments.jpmorgan.com/onboarding/v1/document-requests/87975 \
--header 'Accept: application/json'
Sample response with document requests for US Individual
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.

Sample request to get list of all document requests for a client
Curl
curl --request GET \
--url https://api-mock.payments.jpmorgan.com/onboarding/v1/document-requests?clientId=3002034709 \
--header 'Accept: application/json'
Sample response with document requests for a client
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. 

Sample request to upload a document
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\"}"'
Sample response
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.

Sample request to check the document request outstanding block
Curl
curl --location 'https://api-mock.payments.jpmorgan.com/onboarding/v1/document-requests/87975'
Sample response to check the document request outstanding block
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.

Sample request to upload multiple files for a single document type
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\"}"'
Sample response
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.

Sample request to upload multiple document types for one document request
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\"}"'
Sample response
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. 

Sample request to verify uploaded documents
Curl
curl --location 'https://api-mock.payments.jpmorgan.com/onboarding/v1/documents?clientId=3002034709'

Sample response with all documents uploaded for a client:

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. 

Sample request to download a document
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.

Sample request to check the document request status
Curl
curl --location 'https://api-mock.payments.jpmorgan.com/onboarding/v1/document-requests/87975'
Sample response after submission
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.

Sample request to check the document request outstanding block
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
}