Skip to main content

Documentation

Multi-Target Document Upload

Upload one or more documents to an application in a single request, and link each document to one or more application fields, across sections. For example, one company registry extract can serve as proof of address for the business and as proof of ownership for every shareholder.

To upload a document to a single section, use Upload Document to Application. Multi-Target Document Upload complements that request and does not replace it.

Wait for the response for an upload request before initiating the next upload request. Do not execute multiple threads concurrently.

Note

  • Maximum number of files that can be uploaded in one request is 10.

  • Maximum size of files that can be uploaded in one request is 20 MB.

  • Document file name should be up to 200 characters long.

Parameters
Request Header Parameters
Path Parameters

    • app_token

    • The identifier of the application.

Request Body Parameters

The body of the request must follow the multipart/form-data protocol.

    • <part name>

    • A file. Send one part per document, 1 to 10 parts. The part name is any label you choose, for example registry_extract, and must match a key in document_map. Use the --form parameter to define the path to the document file on your local machine. For example, for a part named registry_extract where the file is located at C:/path/to/file/cvr_extract.pdf, enter:

      --form 'registry_extract=@"C:/path/to/file/cvr_extract.pdf"'

      Supported file types include '*.pdf', '*.csv', '*.jpeg', '*.jpg', '*.png'.

    • document_map

    • A JSON object, sent as a text part, that links each file part to the application fields it applies to. The object is keyed by part name:

      { "<part name>": { "links": [ { "section": "<section>", "field": "<field>" } ] } }

      Every file part needs an entry in document_map, and every entry needs a file part. Each entry needs at least one link. The maximum number of links in one request is 20.

    • section

    • In each link of document_map: the section of the application, named as in Upload Document to Application, for example business, company, AU, owner, shareholder, or shareholder_1. The first instance of a repeated section has no suffix.

    • field

    • In each link of document_map: the field_type of the document field, as returned by Get Application Template, for example address_ref, ownership_ref_type, or id_img.

Response Parameters

Note

Each link in document_map returns one entry in data, in document_map order. Links that pass validation are saved with the status Pending Review. Links that are not saved return the status Not Valid and an error. See also the sample response on this page.

The following parameters are returned for each link:

    • part

    • The file part name from the request.

    • file_name

    • The name of the uploaded file.

    • section

    • The section of the link, as sent.

    • field

    • The field of the link, as sent.

    • token

    • The identifier of the document for this field. Each linked field gets its own token. Value is null if the link was not saved.

    • upload_status

    • Status of the link. Value is Pending Review if the link was saved, and Not Valid if it was not.

    • error

    • The error that occurred during the upload. Value is null when upload is successful.

    • message

    • The explanation of the error. Value is null when the link was saved.

Behavior and Errors

  • Partial success: links that pass validation are saved. The other links are returned with upload_status = Not Valid and an error. This matches the Upload Document to Application request.

  • Uploads add, never replace: each upload adds to the documents of a field. Resending a request adds its documents again.

For more onboarding errors that can also occur with this request, see Onboarding KYB Errors.

  • /v1/partner/onboarding/application/documents/:app_token

  • Multi-Target Document Upload

  • # The extra spaces in document_map are for alignment only, to make the sample easier to read.
# They are not required. JSON ignores spaces between its elements.
curl -X POST 'https://sandboxapi.rapyd.net/v1/partner/onboarding/application/documents/app_4f1c9e2a7b3d4e5f8a9b0c1d2e3f4a5b' \
  -H 'access_key: your-access-key-here' \
  -H 'Content-Type: multipart/form-data' \
  -H 'salt: your-random-string-here' \
  -H 'signature: your-calculated-signature-here' \
  -H 'timestamp: your-unix-timestamp-here' \
  -H 'merchant_account_id: your-merchant-account-here' \
  --form 'registry_extract=@"/Users/Jane/Documents/cvr_extract.pdf"' \
  --form 'passport=@"/Users/Jane/Documents/passport.png"' \
  --form-string 'document_map={
    "registry_extract": {
      "links": [
        { "section": "business",      "field": "address_ref" },
        { "section": "shareholder",   "field": "ownership_ref_type" },
        { "section": "shareholder_1", "field": "ownership_ref_type" }
      ]
    },
    "passport": {
      "links": [
        { "section": "AU", "field": "id_img" },
        { "section": "AU", "field": "not_a_field" }
      ]
    }
  }'
  • {
  "status": {
    "error_code": "",
    "status": "SUCCESS",
    "message": "",
    "response_code": "",
    "operation_id": "a5e8f796-5558-4860-8022-0cc837dd913f"
  },
  "data": [
    {
      "part": "registry_extract",
      "file_name": "cvr_extract.pdf",
      "section": "business",
      "field": "address_ref",
      "token": "file_6bd792ef69804e2a99895405531b6930",
      "upload_status": "Pending Review",
      "error": null,
      "message": null
    },
    {
      "part": "registry_extract",
      "file_name": "cvr_extract.pdf",
      "section": "shareholder",
      "field": "ownership_ref_type",
      "token": "file_1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f",
      "upload_status": "Pending Review",
      "error": null,
      "message": null
    },
    {
      "part": "registry_extract",
      "file_name": "cvr_extract.pdf",
      "section": "shareholder_1",
      "field": "ownership_ref_type",
      "token": "file_9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c",
      "upload_status": "Pending Review",
      "error": null,
      "message": null
    },
    {
      "part": "passport",
      "file_name": "passport.png",
      "section": "AU",
      "field": "id_img",
      "token": "file_0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d",
      "upload_status": "Pending Review",
      "error": null,
      "message": null
    },
    {
      "part": "passport",
      "file_name": "passport.png",
      "section": "AU",
      "field": "not_a_field",
      "token": null,
      "upload_status": "Not Valid",
      "error": "ERROR_INVALID_SECTION_OR_FIELD_FOR_UPLOADED_DOCUMENT",
      "message": "The request attempted to upload a document, but the specified section and/or field for the document file was invalid. The request was rejected. Corrective action: Rerun the request with a valid field and section."
    }
  ]
}
In this section:

The number of seconds elapsed since the beginning of the Unix epoch, which was 00:00:00 GMT on January 1, 1970. 10-digit integer.