1. Contact
  2. Contact Tag

Contact Tag POST

URI

https://{DATACENTER}.brightpearlconnect.com/public-api/{ACCOUNT}
/contact-service/contact/{CONTACT-ID-SET}/tag/{TAG-ID-SET}

Refer to our documentation on URI syntax for more information on how to construct URIs.

Description

This message allows you to add an existing tag to a set of contacts. You may add a tag to one or more contacts per request.

You may not add a tag to a contact if:

  • The contact is already has the tag.
  • The tag does not exist.
  • The contact does not exist.

If the tag does not exist the HTTP status received from this message will be 404 and error indicating tag does not exist.

The response object from this message differs slightly from our usual format as you can perform bulk updates on many resources at once. Given this the response object you receive contains two sections:

  • resourceErrors: This is a map of contact ID to a list of errors that occurred whilst associating that contact.
  • resourceStatus: This is a map of contact ID to HTTP status code for that association.

The HTTP status received from this method will be 200 if everything goes OK. However if there were any errors HTTP 207 will be returned. HTTP 207 means multi-status. In order to determine the outcome of the request, you will need to work though the resourceErrors and resourceStatus to find the cause of the issue.

Please note that in an effort to ease load on our servers, the limit for one request is currently set to 200 contact IDs.

Example 1

Adding tag 12 to contacts with IDs 252-255. All successful, HTTP response status 200.

Request URI

/contact/252-255/tag/12

Response

{
	"response": {
		"resourceErrors": {
			"252": [
			],
			"253": [
			],
			"254": [
			],
			"255": [
			]
		},
		"resourceStatuses": {
			"252": 200,
			"253": 200,
			"254": 200,
			"255": 200
		}
	}
}

Example 2

Try adding tag 12 to contact with ID 255 when it has already been added. HTTP response status 207.

Request URI

/contact/255/tag/12

Response

{
	"response": {
		"resourceErrors": {
			"255": [
				{
					"code": "CONC-035",
					"message": "Tag 12 already associated with Contact 255"
				}
			]
		},
		"resourceStatuses": {
			"255": 409
		}
	}
}

Example 3

Try adding tag 9999 to contact 255. This tag does not exist. HTTP response status 404.

Request URI

/contact/255/tag/9999

Response

{
	"errors": [
		{
			"code": "CONC-034",
			"message": "Tag 9,999 does not exist"
		}
	]
}

Example 4

Try adding tag 12 to contacts with IDs 2, 255 & 888. Contact 255 already has the tag. Contact 888 does not exist. The tag is successfully added to contact 2. HTTP response status 207.

Request URI

/contact/2,255,888/tag/12

Response

{
	"response": {
		"resourceErrors": {
			"2": [
			],
			"255": [
				{
					"code": "CONC-035",
					"message": "Tag 12 already associated with Contact 255"
				}
			],
			"888": [
				{
					"code": "CONC-014",
					"message": "Contact 888 does not exist"
				}
			]
		},
		"resourceStatuses": {
			"2": 200,
			"255": 409,
			"888": 404
		}
	}
}