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: You're here!
Data Models: A brief overview to help you get oriented
API Standards: We're RESTful JSON over https -- familiar, friendly, and effective
File Uploads: Our approach to getting your files where you want them
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?

Introduction

A quick walk though to demonstrate how to add new Content to the 4U system.

As part of this, you'll be creating a Content "container" record, adding the first Content Version record and uploading the associated files.

Step 1. Create the Content record

Creates the Content "container" that will hold the Content Version records. Properties of the Content apply across all of the Content Versions it contains.

POST /api/v1/content
{
  "type": "document",
  "engageApplicable": true,
  "tagIds": [
      96,
      102
  ],
  "description": "This describes the content that will be loaded.",
  "extras": {
    "myIdentifier": "some-unique-identifer"
  }
}

ℹ️ type: "document" indicates this will be for a PDF or PowerPoint type document (not, for example, a video or audio)

ℹ️ tagIds: tag choices are predefined; you can find all available tags and their ids using the GET /api/v1/content-tag endpoint.

ℹ️ extras: this is an optional field that you can use to store any extra data that you want to associate with the record; the intent is that you can use this to tie this record back to specific records in your internal systems. For example, you can use it to store your own internal unique identifier for the record. There are no constraints on the structure of this object (other than being valid json).

Step 2. Create the Content Version record

Using the id of the Content record that was just created (available in the response from the previous POST call), create the first Content Version record.

Example of "advisor use only" content with no FINRA letter

POST /api/v1/content/{contentId}/version/
{
  "title": "Automation created Product Guide",
  "contentFormatId": 122,
  "providerRefCode": "RGS-2490-Y20210",
  "intendedAudience": "advisor_use_only",
  "isFinraRegistered": false,
  "finraNoLetterReasons": ["fa_use_only"],
  "approverName": "Guthrie Saunders",
  "categoryIds": [
    2,
    33
  ],
  "expiresAt": "2034-05-29T00:00:00.000Z",
  "assignedTeamId": 22,
  "assignedUserId": 123456789,
  "extras": {
    "myIdentifier": "some-unique-identifer",
    "myVersionIdentifer": "another-unique-identifer"
  }
}

ℹ️ contentFormatId: format choices are predefined; you can find all available formats and their ids using the GET /api/v1/content-format endpoint.

ℹ️ intendedAudience: public_use or advisor_use_only

ℹ️ finraNoLetterReasons: allowed values include non_registered_product, sma, fa_use_only, non_product, and/or third_party_reprint

ℹ️ categoryIds: categories are predefined; you can find all available categories and their ids using the GET /api/v1/content-category endpoint. Currently you can only choose a single parent/child category. As a convenience, you may specify only the child category.

ℹ️ assignedTeamId: you can find all available teams and their ids using the GET /api/v1/team/submitter endpoint

ℹ️ assignedUserId: the specified user must belong to the specified team; you can find all available users and their ids for a team using the GET /api/v1/team/submitter/{teamId} endpoint where {teamId} is the id of the desired team; you may optionally leave this property out if you wish to assign the record to a team without designating a specific user.

Step 3. Upload the Primary document

Using the id of the Content record (available in the response from Step 1) and the id of the Content Version record (available in the response from Step 2), upload the primary document.

Request a file upload for the Content Version you just created:

POST /api/v1/content/{contentId}/version/{versionId}/file-upload
{
  "type": "primary",
  "fileName": "Fabulous Brochure.pdf"
}

The response to this request will include an uploadUrl that indicates where the file should be uploaded to:

PUT {uploadUrl}
<body of PUT contains the file contents>

Step 4. Upload Supporting documents (if applicable)

If the Content Version requires supporting documents to be submitted to your partner firm in order to obtain approval, this is done exactly as described in Step 3 for uploading the primary document except that you replace the type of "primary" with the type of "supporting".

Step 5. Upload FINRA document (if applicable)

If the Content Version has an associated FINRA filing letter, this is done exactly as performed in Step 3 for uploading the primary document except that you replace the type of "primary" with the type of "finra".

Step 6. Transition the Content Version to Available

At this point, your Content Version is in "draft" status to make it "available" so that it can be shared with one or more partners, you must transition it from "draft" to "available."

Transitioning the status of a record is done by using the transition endpoint on the record.

To list all available transitions for the current status:

GET /api/v1/content/{contentId}/version/{versionId}/transition

which will return a response like:

{
  "status": 200,
  "data": {
    "allowedTransitions": [
      {
        "id": 0,
        "name": "Make Available",
        "isAllowed": true
      }
    ]
  },
  "requestId": "0HN6TUCHBTK3A:00000001"
}

⚠ if isAllowed is false, that means that not all required fields have been populated.

Assuming the transition is allowed, you make your draft record available by POSTing to the same endpoint using the desired transition id:

POST /api/v1/content/{contentId}/version/{versionId}/transition
{
  "transitionId" : 0
}

Questions or comments?

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