Skip to main content

Add or update comments

POST/api/v1/sources/<project>/<source_name>/sync
Permissions required: Edit verbatims
Billable Operation

You will be charged 1 AI unit per created comment, or per updated comment (based on its unique ID) if its text was modified.

curl -X POST 'https://<my_api_endpoint>/api/v1/sources/<project>/<source>/sync' \
-H "Authorization: Bearer $REINFER_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"comments": [
{
"id": "0123456789abcdef",
"messages": [
{
"body": {
"text": "Alice,\n\nHere are the figures for today.\n\nRegards,\nBob"
},
"from": "bob@organisation.org",
"sent_at": "2011-12-11T11:05:10.000000+00:00",
"subject": {
"text": "Today'"'"'s figures"
},
"to": [
"alice@company.com"
]
}
],
"timestamp": "2011-12-11T11:05:10.000000+00:00",
"user_properties": {
"string:Recipient Domain": "company.com",
"string:Sender Domain": "organisation.org"
}
},
{
"id": "abcdef0123456789",
"messages": [
{
"body": {
"text": "Hi Bob,\n\nI think these are the wrong numbers - could you check?\n\nThanks again,\nAlice"
},
"from": "alice@company.com",
"sent_at": "2011-12-11T11:18:43.000000+00:00",
"subject": {
"text": "Today'"'"'s figures"
},
"to": [
"bob@organisation.org"
]
}
],
"timestamp": "2011-12-11T11:18:43.000000+00:00",
"user_properties": {
"string:Recipient Domain": "organisation.org",
"string:Sender Domain": "company.com"
}
}
]
}'

A comment's ID uniquely identifies it within a source. If the provided comment ID does not exist in the source, a new comment will be created. Otherwise, an existing comment will be updated.

NameTypeRequiredDescription
commentsarray<Comment>yesA batch of at most 16384 comments, in the format described in the Comment Reference. Larger batches are faster (per comment) than smaller ones.
Assigned entities

If the contents of "messages" is updated (including non-text fields such as "sent_at"), any assigned entities are discarded. Assigned entities are not discarded if any other field (such as "timestamp" or the contents of "user_properties") is updated. Assigned labels are never discarded.

Large requests

For large requests, this endpoint may take longer to respond. You should increase your client timeout.

Add or update comments from raw emails

POST/api/v1/sources/<project>/<source_name>/sync-raw-emails
Permissions required: Edit verbatims
Billable Operation

You will be charged 1 AI unit per created comment, or per updated comment (based on the email's Message ID) if its text was modified.

curl -X POST 'https://<my_api_endpoint>/api/v1/sources/<project>/<source>/sync-raw-emails' \
-H "Authorization: Bearer $REINFER_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"documents": [
{
"raw_email": {
"body": {
"plain": "Hi Bob,\n\nCould you send me today'"'"'s figures?\n\nThanks,\nAlice"
},
"headers": {
"parsed": {
"Date": "Thu, 09 Jan 2020 16:34:45 +0000",
"From": "alice@company.com",
"Message-ID": "abcdef@company.com",
"References": "<01234@company.com> <56789@company.com>",
"Subject": "Figures Request",
"To": "bob@organisation.org"
}
}
},
"user_properties": {
"number:Deal Value": 12000,
"string:City": "London"
}
}
],
"include_comments": true,
"transform_tag": "name.0.ABCD1234"
}'

Each raw email will be converted to a Re:infer comment. Re:infer will generate the comment's ID based on the email's "Message-ID" header. If a comment with this comment ID does not exist in the source, a new comment will be created. Otherwise, an existing comment will be updated.

When converting a raw email to a comment, Re:infer will clean the email body and generate metadata from email headers. You can set include_comments to true to include the generated comments in the response. The comments will be returned in the format described in the Comment Reference.

NameTypeRequiredDescription
transform_tagstringyesA tag identifying the email integration sending the data. You should have received this tag during integration configuration setup.
documentsarray<Document>yesA batch of at most 16384 documents in the format described below. Larger batches are faster (per document) than smaller ones.
include_commentsbooleannoIf set to true, the comments parsed from the emails will be returned in the response body.
override_user_propertiesarray<string>noUser properties supplied in documents will override auto-generated user properties if their names appear in this list. The user property names in this list should be specified without the type prefix, e.g. as My Property and not string:My Property.

Where Document has the following format:

NameTypeRequiredDescription
raw_emailRawEmailyesEmail data, in the format described in the Comment Reference.
comment_idstringnoIdentifies a comment uniquely. If no comment ID is provided, Re:infer will generate the comment ID from the email's message ID. The format is described in the Comment Reference.
user_propertiesmap<string, string | number>noAny user-defined metadata that applies to the comment. The format is described in the Comment Reference.

Note: Some user properties are generated based on the email content. If these conflict with uploaded user properties, the request will fail with 422 Unprocessable Entity.
Assigned entities

Re:infer will generate the contents of the comment's "messages" from the raw email body and a subset of the raw email headers, taking into account the specified transform tag. If the contents of "messages" in the generated comment is updated, any assigned entities are discarded. Otherwise assigned entities are not discarded. Assigned labels are never discarded.

Large requests

For large requests, this endpoint may take longer to respond. You should increase your client timeout.

Delete comments

DELETE/api/v1/sources/<project>/<source_name>/comments?id=<comment_id0>[&id=<comment_id1>...]
Permissions required: Edit verbatims
curl -X DELETE 'https://<my_api_endpoint>/api/v1/sources/<project>/<source_name>/comments?id=abcdef0123456789' \
-H "Authorization: Bearer $REINFER_TOKEN"

Individual comments can be deleted from a source, using the ID provided when the comment was added.

All data associated with this comment will be permanently deleted.

Get a comment by id

GET/api/v1/sources/<project>/<source_name>/comments/<comment_id>
Permissions required: View sources
curl -X GET 'https://<my_api_endpoint>/api/v1/sources/<project>/<source>/comments/0123456789abcdef' \
-H "Authorization: Bearer $REINFER_TOKEN"

The comment will be returned in the format described in the Comment Reference.

Get comments by thread id

GET/api/v1/sources/<project>/<source_name>/threads?id=<thread_id0>[&id=<thread_id1>...]
Permissions required: View sources
curl -X GET 'https://<my_api_endpoint>/api/v1/sources/<project>/<source>/threads?id=185521538102&id=81745162' \
-H "Authorization: Bearer $REINFER_TOKEN"

For each specified thread ID, the response will contain a list of comment UIDs (in the format of source_id.comment_id) that belong to that thread. Note that you will not get an error if you provide a thread ID that does not exist; instead the corresponding list of comments in the response will be empty.