Contact POST

URI

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

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

Description

This message allows you to create a new contact.
Detailed field description:
Field Name Field Description
salutation Use this field to specify the salutation such as 'Mr.' or 'Mrs.' for the contact. Max length 32 chars.
firstName Use this field to specify the contact's first name. Max length 32 chars.
lastName Use this field to specify the contact's last name/surname. Max length 32 chars.
postAddressIds Create addresses via the Postal Address message and then use this field to specify the IDs of the addresses which are to be used for this contact. Currently, you can specify three types of addresses for a contact:
  • DEF: Default Address Id
  • BIL: Billing/Invoice Address Id
  • DEL: Delivery Address Id
emails Use this field to map an email type to its email details. Currently, only three email types are supported in Brightpearl:
  • PRI - Primary Email
  • SEC - Secondary Email
  • TER - Tertiary Email
telephones Use this field to map a telephone type to a number. Currently, the possible types are:
  • PRI - Primary Telephone
  • SEC - Secondary Telephone
  • MOB - Mobile Telephone
  • FAX - Fax Number
messagingVoips Use this field to map a messaging/VOIP type to a number/name. Currently, the only possible type is:
  • SKP - Skype
websites Use this to map a website type to an address. Currently, the only possible type is:
  • PRI - Primary Website
contactStatusId Use this field to specify the ID of the current status of the contact. This will default to your Brightpearl account's default contact status if one is not specified.
isSupplier Use this field to set whether this contact is a supplier. This will default to false if not specified
isStaff Use this field to set whether this contact is a member of your staff.
organisation
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.
isReceiveEmailNewsletter Use this field to specify whether the contact is to receive an email newsletter. This will default to false if not specified.
priceListId Use this field to specify the ID of the price list that will be used for this contact. This will default to your Brightpearl account's default contact price list if an ID is not specified.
taxCodeId Use this field to specify the ID of the tax code to be used for this contact.
creditLimit Use this field to specify the credit limit of the contact.
creditTermDays Use this field to specify the credit term days of the contact.
currencyId This ID is a Brightpearl specific currency ID. Use this field to specify a valid Brightpearl currency for the contact. This will default to your Brightpearl account's default currency if an ID is not specified.
discountPercentage Use this field to specify the discount applicable to this contact.
taxNumber Use this field to specify the contact's tax number.
staffOwnerContactId Use this field to specify the contact ID of the staff owner who this contact is currently assigned to.
leadSourceId Use this field to specify the ID of the lead source of the current assignment.
accountReference User-provided contact reference (account code). Should be unique.
companyId Internal use only
aliases
eBay Use this field to specify the eBay alias for this contact. Number of characters should not be more than 64.

Organisation Contacts

An organisation can only have one primary contact but can have multiple secondary contacts. A primary contact is the first contact that was created with an organisation name specified. If the primary contact is a supplier then all further (secondary) contacts need to be a supplier. Similarly, if the primary contact is not a supplier then all further (secondary) contacts must not be a supplier.

For example, if you create a contact 'Ms. Primary Contact' at 'Test Organisation' which is a supplier, and 'Test Organaisation' didn't exist previosuly, 'Ms Primary Contact' will become the primary contact for that organisation. If you try to create another contact with the organisation 'Test Organisation' which is not a supplier you will get an error.

Example 1

Create a new contact, Ms Pink Melody, with the minimum set of fields. The response returns the ID of the contact.

Request URI

/contact/

Request body

{
	"salutation": "Ms.",
	"firstName": "Pink",
	"lastName": "Melody",
	"postAddressIds": {
		"DEF": 141,
		"BIL": 141,
		"DEL": 141
	}
}

Response

{
	"response": 288
}

Example 2

Create a new contact, Mr Blue Melody, with the maximum set of fields (excluding organisation information). The response returns the ID of the contact.

Request URI

/contact/

Request body

{
	"salutation": "Mr.",
	"firstName": "Blue",
	"lastName": "Melody",
	"postAddressIds": {
		"DEF": 142,
		"BIL": 142,
		"DEL": 142
	},
	"communication": {
		"emails": {
			"PRI": {
				"email": "blue.melody@brightpearl.com"
			},
			"SEC": {
				"email": "blue.melody@address.com"
			},
			"TER": {
				"email": "blue.melody@another.com"
			}
		},
		"telephones": {
			"PRI": "24526153"
		},
		"messagingVoips": {
			"SKP": "skype-name"
		},
		"websites": {
			"PRI": "www.brightpearl.com"
		}
	},
	"contactStatus": {
		"current": {
			"contactStatusId": 2
		}
	},
	"relationshipToAccount": {
		"isSupplier": false,
		"isStaff": false
	},
	"marketingDetails": {
		"isReceiveEmailNewsletter": true
	},
	"financialDetails": {
		"priceListId": 1,
		"taxCodeId": 8,
		"creditLimit": "1000.0000",
		"creditTermDays": 30,
		"discountPercentage": 15,
		"taxNumber": "k763iudyh236r9fdi"
	},
	"assignment": {
		"current": {
			"staffOwnerContactId": 4,
			"leadSourceId": 4,
			"accountReference": "ACC00001"
		}
	}
}

Response

{
	"response": 289
}

Example 3

Create a primary contact, 'Mr. and Mrs. Smith', for the organisation, 'Test Organisation' which is a supplier. The response returns the ID of the created contact.

Request URI

/contact/

Request body

{
	"salutation": "Mr. and Mrs.",
	"lastName": "Smith",
	"postAddressIds": {
		"DEF": 143,
		"BIL": 143,
		"DEL": 143
	},
	"organisation": {
		"name": "Test Organisation"
	},
	"relationshipToAccount": {
		"isSupplier": true
	}
}

Response

{
	"response": 290
}

Example 4

Create a another, secondary, contact, 'Mr. Joe Bloggs', for the organisation, 'Test Organisation' which is also a supplier. The response returns the ID of the created contact.

Request URI

/contact/

Request body

{
	"salutation": "Mr.",
	"firstName": "Joe",
	"lastName": "Bloggs",
	"postAddressIds": {
		"DEF": 144,
		"BIL": 144,
		"DEL": 144
	},
	"organisation": {
		"name": "Test Organisation"
	},
	"relationshipToAccount": {
		"isSupplier": true
	}
}

Response

{
	"response": 291
}

Example 5

Try to create another (secondary) contact for the organisation, 'Test Organisation' which is not a supplier. An error will be returned as any further contacts that are created for the organisation 'Test Organisation' have to be a supplier.

Request URI

/contact/

Request body

{
	"salutation": "Mr.",
	"firstName": "Brian",
	"lastName": "Bloggs",
	"postAddressIds": {
		"DEF": 141,
		"BIL": 141,
		"DEL": 141
	},
	"organisation": {
		"name": "Test Organisation"
	},
	"relationshipToAccount": {
		"isSupplier": false
	}
}

Response

{
	"errors": [
		{
			"code": "CONB-023",
			"message": "There is already a contact at the company, Test Organisation, set as a supplier. Edit the original contact or vary the company name to continue."
		}
	]
}