POST contacts/save

Save a single contact record. ContactID or email is required. Only data for parameters passed in is saved.

* required

Parameters

Name

Type

Description

contactID

integer

Unique ID of a contact

email-address

A valid email address

userID

integer

ID of system user contact belongs to

customerID

string

ID of record in client system

suppressed

boolean

Opted out of receiving emails

held

boolean

Bad email address (too many bounces)

originalSource

string

Client-specified source of record

firstName

string

lastName

string

company

string

title

string

mobileNumber

string

A valid phone number used for SMS. Return values will be in E.164 format (e.g. +15551234567)

phone

string

fax

string

address1

string

address2

string

city

string

state

string

zipCode

string

country

string

purl

string

Personal URL (PURL) used with emfluence Marketing Platform landing pages. PURLs must be unique per contact. PURLs can contain only letters, numbers, and any of the following characters: .-_!

dateofbirth

date

Full date of birth in yyyy-mm-dd format. To use only month and day, use 1900 as year

ipaddress

string

Source IP of record

notes

string

Extra details about record (internal use)

memo

string

customFields

object

Custom fields (1 to X). Use customFields/search endpoint to determine available custom fields for your account. Each custom field is an object with keys for "label" and "value". When saving, you only need to provide the value. e.g. {"custom1":{"value":"My custom value"}} For existing records, fields not passed in will remain unchanged.

contentVariables

object

Content variables 1 to 10. Each content variable is an object with keys for "label" and "value". When saving, you only need to provide the value. e.g. {"content1":{"value":"My custom value"}}

groupIDs

array[integer]

Add contact to these groups. Contacts cannot be added to dynamic groups.

removeGroupIDs

array[integer]

Remove contact from these groups. Contacts cannot be removed from the "All" group. To manage group-level suppression, use /contacts/saveGroups.

Response Data

Returns a contact object (same as when doing a lookup)

Name	Type	Description
address1	string
address2	string
city	string
company	string
contactID	integer	Unique ID of a contact
contactScore	object	Object containing keys for "dateModified", "value", and "percentile". e.g. {"dateModified":"2018-04-19 21:03:17","value":100,"percentile":48}. If you have multiple contact scores, an additional key for each contact score will be included with an object of "dateModified", "value", "percentile", and "title" keys. This data is read-only and cannot be saved.
contentVariables	object	Content variables 1 to 10. Each content variable is an object with keys for "label" and "value". When saving, you only need to provide the value. e.g. {"content1":{"value":"My custom value"}}
country	string
customerID	string	ID of record in client system
customFields	object	Custom fields (1 to X). Use customFields/search endpoint to determine available custom fields for your account. Each custom field is an object with keys for "label" and "value". When saving, you only need to provide the value. e.g. {"custom1":{"value":"My custom value"}} For existing records, fields not passed in will remain unchanged.
dateAdded	datetime	Date record was added
dateHeld	datetime	Date record was held
dateModified	datetime	Date record was modified
dateOfBirth	date	Full date of birth in yyyy-mm-dd format. To use only month and day, use 1900 as year
dateSuppressed	datetime	Date record was suppressed
email	email-address	A valid email address
fax	string
firstName	string
groupIDs	array[integer]	Groups contact is subscribed to. Excludes groups where contact is suppressed.
held	boolean	Bad email address (too many bounces)
ipAddress	string	Source IP of record
lastActivityDate	datetime	Date contact last viewed an email
lastClickDate	datetime	Date contact last clicked a link in an email
lastName	string
memo	string
mobileNumber	string	A valid phone number used for SMS. Return values will be in E.164 format (e.g. +15551234567)
notes	string	Extra details about record (internal use)
originalSource	string	Client-specified source of record
phone	string
purl	string	Personal URL (PURL) used with emfluence Marketing Platform landing pages. PURLs must be unique per contact. PURLs can contain only letters, numbers, and any of the following characters: .-_!
smsOptOut	array	SMS opt out details for the contact's mobile number
state	string
suppressed	boolean	Opted out of receiving emails
title	string
userID	integer	ID of system user contact belongs to
zipCode	string

Permissions

Method requires the Contacts (Edit) permission

Example Calls

Save contact using email address

POST

/contacts/save

cURL

Copy

curl https://api.emailer.emfluence.com/v1/contacts/save \
	-H "Authorization: Bearer {{accessToken}}" \
	-H "Content-Type: application/json" \
	-X POST \
	-d '{
		"email": "new.record@example.com",
		"firstName": "John",
		"lastName": "Doe",
		"groupIDs": [123,456,789]
	}'

Response Data

{"success":1,"code":0,"data":{"mobileNumber":"","phone":"","state":"","ipAddress":"","firstName":"John","email":"new.record@example.com","contactID":1903512,"groupIDs":[123,456,789],"notes":"","customerID":"","dateSuppressed":"","held":false,"country":"","lastName":"Doe","userID":8665,"purl":"","address1":"","memo":"","address2":"","originalSource":"","dateAdded":"2015-04-23 20:48:10","zipCode":"","dateHeld":"","content2":"","customFields":{"custom1":{"label":"Custom 1","value":""},"custom2":{"label":"Custom 2","value":""},"custom3":{"label":"Custom 3","value":""},"custom4":{"label":"Custom 4","value":""}},"suppressed":false,"content1":"","company":"","content3":"","city":"","dateOfBirth":"","dateModified":"2015-04-23 20:48:11","title":"","fax":""},"requestID":"8B2021F3-7D4E-4218-A46DE3C2A063CC76"}

Save custom field data

Custom fields can have specific data types. Learn more about custom fields

POST

/contacts/save

cURL

Copy

curl https://api.emailer.emfluence.com/v1/contacts/save \
	-H "Authorization: Bearer {{accessToken}}" \
	-H "Content-Type: application/json" \
	-X POST \
	-d '{
			"email": "new.record@example.com",
			"firstName": "John",
			"lastName": "Doe",
			"customFields": {
				"custom1": {
					"value":"Some text value"
				},
				"custom2": {
					"value":123
				},
				"custom3": {
					"value":12.50
				},
				"custom4": {
					"value":"2017-04-28"
				},
				"custom5": {
					"value":true
				},
			}
		}'

Response Data

{"success":1,"code":0,"data":{"full_contact_record_returned":"see contacts/lookup"},"requestID":"EDE868AF-A265-4E54-9E3E9564B27460A8"}

Save contact using ID

If email address is changed to an email that already exists, an duplicate error will be returned.

POST

/contacts/save

cURL

Copy

curl https://api.emailer.emfluence.com/v1/contacts/save \
	-H "Authorization: Bearer {{accessToken}}" \
	-H "Content-Type: application/json" \
	-X POST \
	-d '{
		"contactID": 123,
		"email": "john.doe@example.com",
		"firstName": "John",
		"lastName": "Doe"
	}'

Response Data

{"success":0,"errors":["Email \"john.doe@example.com\" belongs to another record."],"data":{"contactID":456},"code":301,"requestID":"661A0385-C9A5-4897-BA5C2A97966802C2"}

Add/remove contact from groups

POST

/contacts/save

cURL

Copy

curl https://api.emailer.emfluence.com/v1/contacts/save \
	-H "Authorization: Bearer {{accessToken}}" \
	-H "Content-Type: application/json" \
	-X POST \
	-d '{
		"email": "john.doe@example.com",
		"groupIDs": [123,456],
		"removeGroupIDs": [789],
	}'

Response Data

{"success":1,"code":0,"data":{"email":"john.doe@example.com","contactID":1903512,"groupIDs":[123,456],"full_contact_record_returned":"see contacts/lookup"},"requestID":"0591BA96-5EB9-40D2-AAEF1C29FCE2BF90"}

API Console

The console uses production data, so BE CAREFUL!

POST

contacts/save

Request Body

{"groupIDs":"","company":"","address2":"","notes":"","purl":"","contactID":0,"address1":"","removeGroupIDs":"","state":"","firstName":"","held":0,"city":"","ipaddress":"","email":"","userID":0,"memo":"","country":"","originalSource":"","customerID":"","lastName":"","fax":"","zipCode":"","dateofbirth":"","suppressed":0,"customFields":{},"phone":"","title":"","contentVariables":{},"mobileNumber":""}

Access token: *