Context of this document: The Flip Post API for posts, comments, and attachments
Please find a specification for handling posts with the link below.
The Post API allows you to generate posts automatically from third-party systems, such as the intranet, Sharepoint, or ticket systems.
Benefits:
- The manual effort required to maintain systems in sync is significantly reduced.
- Information can be shared quicker, more consistently, and better.
Creating, updating and deleting posts
Please note:
- The Post API has a rate limit of 3 requests per second. In case of exceeding the rate limit, the API will return the HTTP Status
429
. - The Post API has a limited body size of 200 KiB. In case of exceeding the limit, the API will return the HTTP Status
400
. - The group of the
group_id
must exist and the user, which is used to authenticate for the API, must be a group-member of the group. In case the group only allows posts to be created by admins, the user needs to be an admin as well.
Create a post
To create a post via the API, at least the group_id
and the title
must be given. Additionally, a body
in HTML as well as an external_id
can be added. Make sure the HTML of the body
is valid. In the case of an invalid HTML, the API returns an error.
Request:
POST /api/external/post/v1/posts
{
"group_id": "306db4e0-7449-4501-b76f-075576fe2d8f",
"title": "This is a Headline",
"body": "Some content for a post with a word in <b>bold</b>!"
}
Response:
The response will contain the ID of the newly created post.
{
"post_id": "b19c042c-e8ac-4f4f-9eae-0b201211f7f1"
}
This will create the following post in the given group:
Create a post with a file attached
After uploading a file via the attachment endpoint, the attachment_id
is returned. This ID can be inserted into the POST
request via the attachments
array.
In the following example, we create a post after uploading a pdf
and a jpeg
to the Attachment API.
Request:
POST /api/external/post/v1/posts
{
"group_id": "306db4e0-7449-4501-b76f-075576fe2d8f",
"title": "This is a headline",
"body": "A post with an image and a file attachment",
"attachments": [
{ "attachment_id": "2eb9e54a-3af9-4a9c-94b7-2e76d5a4c052" },
{ "attachment_id": "1cb43fb1-93d7-41e9-9a0c-af48827995b4" }
]
}
Be sure to check the success of the media upload via the Attachment API.
This will create the following post in the given group:
Create a post with inline images & videos
After uploading an image or video via the attachment endpoint, the attachment_id
is returned. This attachment_id
must then be inserted in the attachments
list in the POST
request, as well as in the src
attribute of the <img>
/<video>
tag in the HTML body
.
In the following example, we create a post with an inline image after uploading a jpeg
to the attachment endpoint.
Request:
POST /api/external/post/v1/posts
{
"group_id": "306db4e0-7449-4501-b76f-075576fe2d8f",
"title": "This is a headline",
"body": "<p>A post with an inline image & video</p><img src='2eb9e54a-3af9-4a9c-94b7-2e76d5a4c052'><video src='1239e54a-1gds-sf4a-94b7-2e76d5a4c892'></video>",
"attachments": [
{ "attachment_id": "2eb9e54a-3af9-4a9c-94b7-2e76d5a4c052" },
{ "attachment_id": "1239e54a-1gds-sf4a-94b7-2e76d5a4c892" }
]
}
Be sure to check the success of the media upload via the Attachment API.
Update a post
The post can only be updated by using the post_id
and not by the external_id
. The group of the post cannot be changed this way.
Request:
PUT /api/external/post/v1/posts/b19c042c-e8ac-4f4f-9eae-0b201211f7f1
{
"title": "This is a headline",
"body": "Some changed content"
}
The post is now changed.
Delete a post
A post can only be deleted by using the post_id
and not by the external_id
.
DELETE /api/external/post/v1/posts/b19c042c-e8ac-4f4f-9eae-0b201211f7f1
Working with posts by external_id
Specifically, when working with integrations, where post content is provided through a secondary system, the external_id
on the post entity can be leveraged.
Please note and keep in mind:
- There is no enforcement of uniqueness of
external_id
on any Flip entity. - For clarity,
external_post_id
is used to reference theexternal_id
on the Flippost
entity.
Find a post by external_id
To locate a post by external_id
, request posts via the corresponding endpoint. Unless it makes sense, keep all other parameters as null. The responding JSON will provide an array of matching Flip post GUIDs along with lifecycle timestamps.
Request:
GET /api/external/post/v2/posts?external_post_id=<foo>
Please note:
- Should the array be empty, no post by that
external_post_id
/external_id
exists. - Should multiple posts be in the array, the integration has not enforced uniqueness. Please handle this behavior on the integration side.
Formatting posts
Each post in Flip can have a formatted body. The API allows adding a body to a post as HTML. Because Flip currently does not support all HTML tags, the transmitted HTML will be checked for its validity. This is done partly because of restrictions on what should be shown in the Flip App for user experience, especially on mobile devices.
Two possibilities exist when the HTML is not valid.
- The HTML is syntactically invalid. This can be checked by any HTML validator.
- Illegal HTML tags are used (see the table below to check for all allowed HTML tags).
In case of an invalid HTML, the API will return specific errors.
Allowed HTML Tags
You can use any of the following HTML tags to format text in your posts.
HTML Tag Name | Description |
---|---|
<a> |
It is termed as anchor tag, and it creates a hyperlink or link. |
<b> |
It is used to make a text bold. |
<br> |
It is used to apply a single line break. |
<em> |
It is used to emphasize the content applied within this element. |
<h1> |
It defines a heading for an HTML document |
<h2> |
It defines a heading for an HTML document |
<h3> |
It defines a heading for an HTML document |
<i> |
It is used to represent a text in some different voice. |
<li> |
It is used to represent items in a list. |
<ol> |
It defines an ordered list of items. |
<p> |
It represents a paragraph in an HTML document. |
<s> |
It renders text which is no longer correct or relevant. |
<strong> |
It is used to define important text. |
<u> |
It is used to render enclosed text with an underline. |
<ul> |
It defines an unordered list of items. |
<img> |
It renders an image |
HTML Errors
In case of an invalid HTML, a 400 BAD REQUEST
with a json
response with two fields error_code
and message
is returned.
Case | ErrorCode | ErrorMessage (example) |
---|---|---|
The HTML markup sent by the client is invalid. | INVALID_HTML | HTML is invalid |
The HTML markup the client sent contains disallowed tags. (example usage of <video> tag) | DISALLOWED_TAGS | Tag(s) VIDEO are not allowed |
In the following are the Responses listed in the json
format.
{
"error_code": "INVALID_HTML",
"message": "HTML is invalid"
}
Example response to invalid HTML.
{
"error_code": "DISALLOWED_TAGS",
"message": "Tag(s) VIDEO are not allowed"
}
Response body to a request that included disallowed tags.
Comments
0 comments
Please sign in to leave a comment.