Contact GET

URI

https://{DATACENTER}.brightpearl.com/public-api/{ACCOUNT}
/contact-service/contact/{ID-SET}

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

Description

This resource allows you to fetch contacts. All contact types (customers, staff and suppliers) are included in the results.

No more than 200 contacts can be returned in a single request. If you omit the ID set from the URL, or request an ID set larger than 200, one page of 200 contacts will be returned. Meta data showing the number of contacts returned and whether more pages of results are available is included in the response as shown in the examples below.

If the pagination element indicates that there are more pages available, add a firstResult query parameter. With the default page size of 200, use firstResult=201 for the second page, firstResult=401 for the third page and so on. Alternatively adjust the ID set you're requesting according to the last ID in list.

Note the firstResult and lastResult values included in the pagination element are not contact IDs, they are indexes in the set of all contacts in the ID set requested (with invalid IDs ignored). The first contact in the first page of results is index 1.

You may customise the number of results returned on each page with the pageSize parameter, and request the newest contacts first using sort=contactId|DESC.

Detailed field description

Field Name Field Description
postAddressIds This field contains three values:
  • DEF: Default Address ID
  • BIL: Billing Address ID
  • DEL: Delivery Address ID
postalAddresses (Optional) A list containing the full details of every address associated with the contact.
emails This object contains three possible objects which represent the three emails a contact can currently have within Brightpearl. The keys have three values:
  • PRI - Primary Email
  • SEC - Secondary Email
  • TER - Tertiary Email
telephones This is a map of telephone type to number. The possible types currently are:
  • PRI - Primary Telephone
  • SEC - Secondary Telephone
  • MOB - Mobile Telephone
  • FAX - Fax Number
messagingVoips This is a map of messaging/VOIP application type to number. The possible types currently are:
  • SKP - Skype
websites This is a map of website type to address. The possible types currently are:
  • PRI - Primary Website
isSupplier Defines whether this contact is a supplier.
isStaff Defines whether this contact is a member of your staff within your Brightpearl account.
organisationId Use this field to set the organisation ID which the contact is the primary/secondary contact for.
name Use this field to set the organisation name which the contact is the primary/secondary contact for.
tradeStatus Defines whether this contact is a trade or retail customer. Permitted values are:
  • UNKNOWN - not known
  • RETAIL - retail customer
  • TRADE - trade customer
customFields (Optional) A map of custom field code to value.
nullCustomFields (Optional) A List of custom field codes which currently have a value of null.
contactTags A list of contact tag IDs associated with the contact.
aliases eBay - eBay alias
companyId Internal use only

Note: to include customFields, nullCustomFields and postalAddresses please see Include Optional Sections.

Example 1

Requesting the contact with ID 200, including custom fields and full postal addresses.

Request URI

/contact/200?includeOptional=customFields,postalAddresses

Response

{
	"response": [
		{
			"contactId": 200,
			"isPrimaryContact": true,
			"salutation": "Mr.",
			"firstName": "Testy",
			"lastName": "McTester",
			"postAddressIds": {
				"DEF": 107,
				"BIL": 107,
				"DEL": 113
			},
			"postalAddresses": {
				"107": {
					"addressLine1": "34 Lime St",
					"addressLine2": "Barton",
					"addressLine3": "Sheffield",
					"addressLine4": "South Yorkshire",
					"postalCode": "S1 4RT",
					"countryIsoCode": "GBR",
					"countryId": 222
				},
				"113": {
					"addressLine1": "Yet another misc address",
					"addressLine2": "Yet another town",
					"addressLine3": "Yet another city",
					"addressLine4": "Yet another state",
					"postalCode": "YA1 1MA",
					"countryIsoCode": "GBR",
					"countryId": 222
				}
			},
			"communication": {
				"emails": {
					"PRI": {
						"email": "tom@brightpearl.com"
					},
					"SEC": {
						"email": "roger.doger@test.com"
					},
					"TER": {
						"email": "dog@test.com"
					}
				},
				"telephones": {
					"PRI": "+44 45895485",
					"SEC": "014568595487",
					"MOB": "07555555445"
				},
				"messagingVoips": {
					"SKP": "roger.doger1212"
				},
				"websites": {
					"PRI": "test.com"
				}
			},
			"contactStatus": {
				"current": {
					"contactStatusName": "Prospecting",
					"contactStatusId": 3
				},
				"history": [
					{
						"contactStatusName": "Suspect",
						"contactStatusId": 2,
						"occuredOn": "2011-07-29T10:46:10.000+01:00",
						"staffContactId": 201
					},
					{
						"contactStatusName": "Prospecting",
						"contactStatusId": 3,
						"occuredOn": "2011-07-29T11:06:29.000+01:00",
						"staffContactId": 201
					}
				]
			},
			"relationshipToAccount": {
				"isSupplier": false,
				"isStaff": false
			},
			"marketingDetails": {
				"isReceiveEmailNewsletter": true
			},
			"financialDetails": {
				"priceListId": 2,
				"nominalCode": "4000",
				"taxCodeId": 8,
				"creditLimit": "1000.0000",
				"creditTermDays": 30,
				"currencyId": 1,
				"discountPercentage": 12.90,
				"taxNumber": "k763iudyh236r9fdi"
			},
			"assignment": {
				"current": {
					"staffOwnerContactid": 201,
					"departmentId": 1,
					"leadSourceId": 3,
					"accountReference": "#2321A"
				}
			},
			"organisation": {
				"organisationId": 200,
				"name": "Rogers Organisation"
			},
			"tradeStatus": "UNKNOWN",
			"createdByid": 2,
			"createdOn": "2011-07-14T17:20:10.000+01:00",
			"updatedOn": "2011-07-29T11:06:29.000+01:00",
			"customFields": {
				"PCF_SELECT": {
					"id": 6,
					"value": "Option 2"
				},
				"PCF_DATE": "2011-09-21T00:00:00.000+01:00",
				"PCF_YESNO": false,
				"PCF_FREETXT": "bla",
				"PCF_LARGETXT": "jkk",
				"PCF_NUMERIC": 120
			},
			"contactTags": "12,14,15",
			"aliases": {
				"eBay": "ebay_272_"
			},
			"companyId": 1
		}
	],
	"pagination": {
		"morePagesAvailable": false,
		"resultsReturned": 1,
		"firstResult": 1,
		"lastResult": 1
	},
	"sorting": [
		{
			"field": "contactId",
			"direction": "ASC"
		}
	]
}

Example 2

Requesting the contacts with IDs 200-201.

Request URI

/contact/200-201/

Response

{
	"response": [
		{
			"contactId": 200,
			"isPrimaryContact": true,
			"salutation": "Mr.",
			"firstName": "Testy",
			"lastName": "McTester",
			"postAddressIds": {
				"DEF": 109,
				"BIL": 119,
				"DEL": 120
			},
			"communication": {
				"emails": {
					"PRI": {
						"email": "email1"
					},
					"SEC": {
						"email": "email2"
					},
					"TER": {
						"email": "email3"
					}
				},
				"telephones": {
					"PRI": "tel1 main",
					"SEC": "tel 2",
					"MOB": "mobile"
				},
				"messagingVoips": {
					"SKP": "skype"
				},
				"websites": {
					"PRI": "web"
				}
			},
			"contactStatus": {
				"current": {
					"contactStatusName": "Prospecting",
					"contactStatusId": 3
				},
				"history": [
					{
						"contactStatusName": "Suspect",
						"contactStatusId": 2,
						"occuredOn": "2011-07-29T10:46:10.000+01:00",
						"staffContactId": 201
					},
					{
						"contactStatusName": "Prospecting",
						"contactStatusId": 3,
						"occuredOn": "2011-07-29T11:06:29.000+01:00",
						"staffContactId": 201
					}
				]
			},
			"relationshipToAccount": {
				"isSupplier": false,
				"isStaff": false
			},
			"marketingDetails": {
				"isReceiveEmailNewsletter": true
			},
			"financialDetails": {
				"priceListId": 2,
				"nominalCode": "4000",
				"taxCodeId": 8,
				"creditLimit": "1000.0000",
				"creditTermDays": 30,
				"currencyId": 1,
				"discountPercentage": 10.10,
				"taxNumber": "k763iudyh236r9fdi"
			},
			"assignment": {
				"current": {
					"staffOwnerContactid": 201,
					"departmentId": 1,
					"leadSourceId": 3
				}
			},
			"organisation": {
				"organisationId": 200,
				"name": "Rogers Organisation"
			},
			"tradeStatus": "UNKNOWN",
			"createdByid": 2,
			"createdOn": "2011-07-14T17:20:10.000+01:00",
			"updatedOn": "2011-07-29T11:06:29.000+01:00",
			"contactTags": "12,14,15",
			"aliases": {
				"eBay": "ebay_272_"
			},
			"companyId": 1
		},
		{
			"contactId": 201,
			"isPrimaryContact": true,
			"salutation": "Mr.",
			"firstName": "Roger",
			"lastName": "Doger",
			"postAddressIds": {
				"DEF": 109,
				"BIL": 119,
				"DEL": 120
			},
			"communication": {
				"emails": {
					"PRI": {
						"email": "roger.doger@test.com"
					},
					"SEC": {
						"email": "roger.doger@gmail.com2"
					}
				},
				"telephones": {
					"PRI": "0455566554465"
				},
				"messagingVoips": {
					"SKP": "trgfdf.fdsfsd"
				},
				"websites": {
					"PRI": "www.roger.doger.com"
				}
			},
			"contactStatus": {
				"current": {
					"contactStatusName": "Prospecting",
					"contactStatusId": 3
				},
				"history": [
					{
						"contactStatusName": "Suspect",
						"contactStatusId": 2,
						"occuredOn": "2011-07-29T10:46:10.000+01:00",
						"staffContactId": 201
					},
					{
						"contactStatusName": "Prospecting",
						"contactStatusId": 3,
						"occuredOn": "2011-07-29T11:06:29.000+01:00",
						"staffContactId": 201
					}
				]
			},
			"relationshipToAccount": {
				"isSupplier": false,
				"isStaff": false
			},
			"marketingDetails": {
				"isReceiveEmailNewsletter": true
			},
			"financialDetails": {
				"priceListId": 23,
				"nominalCode": "4001",
				"taxCodeId": 9,
				"creditLimit": "50.0000",
				"creditTermDays": 30,
				"currencyId": 1,
				"discountPercentage": 0,
				"taxNumber": "k763iudyh236r9fdi"
			},
			"assignment": {
				"current": {
					"staffOwnerContactid": 201,
					"departmentId": 1,
					"leadSourceId": 3
				}
			},
			"organisation": {
				"organisationId": 200,
				"name": "Rogers Organisation"
			},
			"tradeStatus": "RETAIL",
			"createdByid": 2,
			"createdOn": "2011-07-14T17:20:10.000+01:00",
			"updatedOn": "2011-07-29T11:06:29.000+01:00",
			"contactTags": "12,14,15",
			"aliases": {
			},
			"companyId": 1
		}
	],
	"pagination": {
		"morePagesAvailable": false,
		"resultsReturned": 2,
		"firstResult": 1,
		"lastResult": 2
	},
	"sorting": [
		{
			"field": "contactId",
			"direction": "ASC"
		}
	]
}