Looking for something else?

Overview: An introduction and high-level overview
Sandbox Environments: The freedom and security to iterate quickly with production-quality data
Authentication: The ins and outs of OAuth 2.0 and how to obtain access tokens
Getting Started: Examples to help you get straight to work using our APIs
Data Models: A brief overview to help you get oriented
API Standards: We're RESTful JSON over https -- familiar, friendly, and effective
File Uploads: You're here!
API Documentation: A live swagger UI using OpenAOI 3.0.1 that plays nicely with Postman and similar tooling
FAQ: We all have questions. Right?

File Uploads

There are a number of instances where it is necessary to upload and associate a file (or files) with some existing record.

In all cases, the basic file upload flow is the same two-step process:

Request an upload as a GET to the record's /file-upload endpoint. The response will contain an upload id, an upload url, and an upload method
Send the body of your file to the indicated upload url using the indicated method (typically PUT)

Step I: Request an upload

In this example, a request is being made to attach a FINRA filing PDF document to a fictional Content Version record identified by Content Id 1234 and Version Id 4567.

This Content Version record is identified by the resource path:

/content-service/api/v1/content/1234/version/4567

In order to initiate a file upload to attach a file to this Content Version record, you would use its file-upload endpoint with a JSON payload as shown here:

POST /content-service/api/v1/content/1234/version/4567/file-upload

  {
    "type": "finra",
    "fileName": "Example FINRA letter.pdf"  
  }

The POST request above specifies the type of the file and the fileName including the extension. (See the API documentation for all allowed file types; for a Content Version record, the allowed values are currently primary, finra, and supporting.)

The response to the POST request will look something like:

{
  "status": 201,
  "data": {
    "id": "888ff6ee-9dbf-4b24-a1ba-963ef0abe6cb",
    "status": "created",
    "url": "https://<upload-url>/...",
    "method": "PUT",
    "createdAt": "2024-05-10T04:02:57.8566543Z",
    "updatedAt": "2024-05-10T04:02:57.8566543Z"
  },
 "requestId": "0HN3GKH9CK6J4:00000027"
}

Step II: Upload File

Upload the contents of the file to the url indicated in the previous response.

As an example, a curl command for uploading a file would look like:

 curl "https://<upload-url>/...' \
   --header "Authorization: Bearer ${ACCESS_TOKEN}" \
   --upload-file "./Example FINRA letter.pdf"

Upload Statuses

As you may have noticed in the example response above, upload records have statuses that indicate their current state.

When first requested, the status is created. Once an upload has been completed, the status transitions to uploaded. Server-side processing of the file initiates automatically after upload. Upon completion of this processing, the file is attached to the desired record and the status transitions to processed. If something goes wrong with the processing, the status will be set to failed.

At anytime, the current status of an upload can be requested using its id. Using the example above, the status of the upload could be checked using:

GET /content-service/api/v1/content/1234/version/4567/file-upload/888ff6ee-9dbf-4b24-a1ba-963ef0abe6cb

which might return a response like:

{
  "status": 201,
  "data": {
    "id": "888ff6ee-9dbf-4b24-a1ba-963ef0abe6cb",
    "status": "processed",
    "url": "https://<upload-url>/...",
    "method": "PUT",
    "createdAt": "2024-05-10T04:02:57.8566543Z",
    "updatedAt": "2024-05-10T04:03:02.985893Z"
  },
 "requestId": "0HN3GKH9CK6J4:00000027"
}

Sequence Diagram Summary

Questions or comments?

We're here 4U – integration@4uplatform.com