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: You're here!
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?

RESTful

The 4U API is designed to simplify and streamline the process of building integrations with 4U and is built using familiar RESTful standards including JSON over HTTPS.

At 4U, we believe that consistent, predictable and well-documented standards are a necessary component of every good API.

Methods

We follow the standard RESTful convention of mapping HTTP methods to operations:

GET - Retrieves a resource or resources, eg retrieving an object by id or performing a search
POST - Creates a new resource, eg creating a new Content record
PUT - Updates an existing resource in its entirety, eg updating all fields of a draft Content record
PATCH - A partial update of an existing resource, eg updating a singe field of a draft Content record
DELETE - Deletes an object; due to the nature of 4U as a compliance system, this is not supported on most resources.

URIs

Paths

URI paths adhere to the following convention:

https://<host>/<service-name>/api/v<version_number>/path/to/some-resource

For example,

https://<your-sandbox-environment>/content-service/api/v1/content-format

As seen, all apis are path-versioned and use kebab-casing.

Query Params

Query params also use kebab-casing

Versioning

All APIs are versioned using path-specified versioning as described above.

Any breaking change to the API will result in a new version.

Adding new fields is not considered a breaking change. Removing fields, changing the type of the value, or changing the meaning of the field is considered a breaking change.

Response Formats

All API response bodies will consist of a json object; a response body will never be: empty, an array, or a primitive value (string, number, etc). All json will be expressed with camelCase formatting.

Responses fall into one of three categories: success, failure, or error. The latter two will adhere to the Problem Details for HTTP APIs [RFC9457] specification.

Response Type	Description	Keys
Success 2xx response codes	All went well, and (usually) some data was returned.	`status` (number) – an integer value >=200 and < 300 `data` (object \| null) – The value will represent the results of the request. In rare cases where there is no meaningful response data, it may be `null`. `requestId` (string) – a unique identifier for the request
Failure 4xx response codes	There was a problem with authorization, the data submitted, or some pre-condition of the API call wasn't satisfied.	https://datatracker.ietf.org/doc/html/rfc9457#name-members-of-a-problem-detail `status` (number) – an integer value >=400 and < 500 `type` (string) – a URI reference that identifies the problem type. `title` (string) – a short, human-readable summary of the problem type. `requestId` (string) – a unique identifier for the request
Error 5xx response codes	An error occurred in processing the request. This shouldn't happen!	https://datatracker.ietf.org/doc/html/rfc9457#name-members-of-a-problem-detail `status` (number) – an integer value >=500 and < 600 `message` (string) – a human readable message describing the error `type` (string) – a URI reference [RFC3986] that identifies the problem type. `title` (string) – a short, human-readable summary of the problem type. `requestId` (string) – a unique identifier for the request

Sample Responses

The following are all examples of valid response formats:

Success

{
   "status": 200,
   "data": {
      "contentFormats": [
         {"id": "149", "name": "Article Reprint"},
         {"id": "129", "name": "Audio Presentation"},
         {"id": "122", "name": "Brochure"},
         {"id": "350", "name": "Capital Gains / YE Distributions"},
         {"id": "126", "name": "Commentary"},
         {"id": "175", "name": "Email Blast"},
         {"id": "317", "name": "Event Invitation - Advisor"},
         {"id": "318", "name": "Event Invitation - Client"},
         {"id": "125", "name": "Fact Sheet"},
         {"id": "176", "name": "Flyer"},
         {"id": "177", "name": "Fund Review"},
         {"id": "178", "name": "Mailer"},
         {"id": "179", "name": "Newsletter"},
         {"id": "180", "name": "Other"},
         {"id": "124", "name": "Presentation / Seminar"},
         {"id": "127", "name": "Sales Idea"},
         {"id": "53", "name": "Video"},
         {"id": "50", "name": "White Paper"},
         {"id": "119", "name": "Workbook"}
      ]
   },
   "requestId": "0HN3G6LQ159JS:00000004"
}

Failure

A 401 example due to an expired access token:

{
  "title": "Bad Request",
  "requestId": "9be72a1d-91be-48f9-bb12-8c8b30477d46",
  "detail": "Jwt is expired",
  "type": "https://httpstatuses.io/401",
  "status": 401
}

Error

An unexpected error occurred within the 4U system:

{
 "type": "https://httpstatuses.io/404",
 "title": "Internal Server Error",
 "status": 500,
 "detail": "The application encountered an unexpected error, this error has been logged and the issue will be investigated. Please include the requestId in any correspondences.",
 "requestId": "0HN3ASC2T57H7:00000001"
}

Request Body

All RESTful APIs will accept camelCase JSON with the first letter being lowercase and the start of each subsequent word uppercase.

Questions or comments?

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