Coding

Bulk action sends a set of action on mentions in reports.

Field	Mandatory	Type	Description
action	yes	string	Type of action. One of : update
report_id	yes	string	ID of the report
mention_id	yes	string	ID of the mention
payload	yes	object	list of changes you want to apply

Here is the definition of the payload object

Field	Mandatory	Type	Description
sentiment	no	string	Sentiment name. One of : positive, neutral, negative, unassigned
channel	no	string	Type of channel : owned or earned
tags	no	array of string	List of mention’s tags to set (will override existing tags)
review.status	no	string	One of : reviewed, unreviewed, deleted
language	no	string	ID of the language of the mention, see language resource
location.country	no	string	ID of the country of the mention, see country resource

While all payload parameters are optional, you need to provide at least one when performing a request

On success

an HTTP 204 No Content is returned when everything works

valid request

we are sending 2 updates in one request

POST https://rest.synthesio.com/coding/v1/_bulk HTTP/1.1
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

{
	"data": [
		{
			"action": "update",
			"report_id": "100001",
			"mention_id": "20001",
			"payload": {
				"sentiment": "neutral",
				"tags": [
					"foo",
					"bar"
				]
			}
		},
		{
			"action": "update",
			"report_id": "100001",
			"mention_id": "20002",
			"payload": {
				"sentiment": "positive",
				"review": {
					"status": "reviewed"
				},
				"language": "fra",
				"location": {
					"country": "FRA"
				}
			}
		}
	]
}

both of them succeeded, you receive a HTTP 204 No Content

HTTP/1.1 204 No Content

examples of errors

validation errors

Here we sent 5 updates but only one was valid

as you can see in the counter object, provided=5, success=1 and errors=4

bulk_index information helps you to identify that mention #0, #1, #3 and #4 failed

For a better understanding, please find here is the data we posted to get this error

To help you to debug, you MAY also get extra information in the meta field of the error.

Field	Type	Description
action	string	Type of action. One of : update
mention_id	string	ID of the mention
report_id	string	ID of the report
bulk_index	int	the position (starting at 0) of the mention in the posted data

• a counter object MAY be returned in data element

Field	Type	Description
provided	int	number of changes posted
success	int	number of changes taken into account
errors	int	number of changes not taken into account

• meaning of possible values for the HTTP status code of the request

Val	Description
204	No error
200	The data you posted cannot be accepted (validation errors)
400	The data you posted cannot be read
401	Invalid identification
50X	A temporary internal error occurred you should retry, if it persists you should contact the support team

HTTP/1.1 200 OK
Content-Type: application/json

{
	"data": {
		"counter": {
			"provided": 5,
			"success": 1,
			"errors": 4
		}
	},
	"errors": [
		{
			"status": 400,
			"title": "Bad Request",
			"detail": "non-empty `payload` field is required",
			"meta": {
				"report_id": "100001",
				"action": "update",
				"mention_id": "200001",
				"bulk_index": 0
			}
		},
		{
			"status": 400,
			"title": "Bad Request",
			"detail": "invalid value for `human_review_status` field: 17",
			"meta": {
				"report_id": "100001",
				"action": "update",
				"mention_id": "200003",
				"bulk_index": 2
			}
		},
		{
			"status": 400,
			"title": "Bad Request",
			"detail": "report not found",
			"meta": {
				"report_id": "100404",
				"action": "update",
				"mention_id": "200001",
				"bulk_index": 3
			}
		},
		{
			"status": 400,
			"title": "Bad Request",
			"detail": "mention not found in report",
			"meta": {
				"report_id": "100001",
				"action": "update",
				"mention_id": "200404",
				"bulk_index": 4
			}
		}
	]
}

POST https://rest.synthesio.com/coding/v1/_bulk HTTP/1.1
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

{
	"data": [
		{
			"action": "update",
			"report_id": "100001",
			"mention_id": "20001",
			"payload": {
			}
		},
		{
			"action":"update",
			"report_id": "100001",
			"mention_id": "20002",
			"payload" :{
				"sentiment": "positive",
				"review": {
					"status": "reviewed"
				}
			}
		},
		{
			"action":"update",
			"report_id": "100001",
			"mention_id": "20003",
			"payload" :{
				"sentiment": "negative",
				"review": {
					"status": "17"
				}
			}
		},
		{
			"action":"update",
			"report_id": "100404",
			"mention_id": "20001",
			"payload" :{
				"sentiment": "neutral"
			}
		},
		{
			"action":"update",
			"report_id": "100001",
			"mention_id": "20404",
			"payload" :{
				"review": {
					"status": "deleted"
				}
			}
		}
	]
}