Create a contact

This endpoint will create a new contact. The duplications are checked on the email address level and the workspace level together.

Endpoint

cURL

POST https://api.mailstand.com/contacts

Payload

These fields are allows required in the payload when creating a contact.

Required Fields

Field	Type	Required	Description
owner_key	string	true	The API of the user who is the owner of the contact.
workspace	string	true	The workspace ID that you want to query. This always start with space_.
email	string	true	The email address of the contact.
upload_options[duplicates]	object/string	true	This is either skip, overwrite or update_missing_fields. You can learn more about the deduplication options here. The most common option is skip.
upload_options[strict_validation]	object/boolean	true	If true we run the validation on our standard fields. You can learn more about validations here and here. The most common choice is false.
upload_options[campaign]	object/string	true	The campaign that you want to upload the contact to. This always starts with camp_. If you don't want to add a contact to a campaign, you can set the value to null.

Optional Fields
Mailstand automatically creates default fields that you can use while uploading contacts. If you require custom fields see how custom fields are used when uploading a contact.

Field	Type
first_name	Contact's first name.
middle_name	Contact's middle name.
last_name	Contact's last name.
full_name	Contact's full name.
nickname	Contact's nickname.
title	Contact's title or also known as role.
mobile_phone	Contact's mobile / cell phone number.
work_phone	Contact's work phone number.
home_phone	Contact's home phone number.
voip_phone	Contact's VOIP phone number.
other_phone	Contact's other phone number.
company_name	Contact's company name. Typically an informal name like "Acme".
company_formal_name	Contact's formal company name. Typically formal name like "Acme, Inc.".
company_industry	Contact's company industry.
address_1	Contact's address line one.
address_2	Contact's address line two.
city	Contact's city.
state	Contact's state. You can use prefix (like CA) or full name (like California).
zip	Contact's zip code.
country	Contact's country. You can use prefix (US) or full name (United States).
region	Contact's region.
timezone	Contact's timezone. You can find a list of valid timezone inputs here.
gender	Contact's gender.
occupation	Contact's occupation.
linkedin	Contact's LinkedIn URL or LinkedIn Handle.
twitter	Contact's Twitter URL or Twitter Handle.
stack_overflow	Contact's StackOverflow URL or StackOverflow Handle.
website	Contact's website.
website_2	Contact's 2nd website.
website_3	Contact's 3rd website.
personal_note	Contact's personal note.
personal_note_2	Contact's 2nd personal note.
personal_note_3	Contact's 3rd personal note.
job_start_date	Contact's job start date.
school	Contact's school.
graduation_date	Contact's graduation date.
degree	Contact's degree.

Using Custom Variables

When uploading contacts with custom variables you will have to upload with the custom_ prefix. You can use the List fields on a workspace endpoint to get a list of variables for the workspace and what fields line up with the custom_ prefix.

Payload Example

When sending an API call you only need to provide the required fields and then the optional fields you would like to add. Here's an example below.

JSON

{
    "owner_key": "key_abc123efg4567hij",
    "workspace": "space_987zyx654abc",
    "first_name": "John",
    "middle_name": "J",
    "last_name": "Barnes",
    "full_name": "John J Barnes",
    "nickname": "Mike",
    "email": "[email protected]",
    "title": "CEO & Founder",
    "company_name": "Acme",
    "company_formal_name": "Acme, Inc.",
    "work_phone": "1 555-555-5555",
    "custom_1": "My First Custom Field",
    "custom_2": "My 2nd Custom Field",
    "upload_options": {
        "duplicates": "skip",
        "strict_validation": false,
        "campaign": "camp_abc987zyx123"
    }
}

200 or 201 Response

On a successful upload we will either pass a 200 or 201 response depending on what happened. Here's some example outputs

Example 1: A new contact was created

JSON

{
		"status": "added",
		"id": "contact_abc123",
		"details": null
}

Example 2: A contact was skipped due to a duplicate contact added

JSON

{
		"status": "skipped",
		"id": null,
		"details": "Deuplicate contact."
}

Example 3: If fields were overwritten on a contact.

JSON

{
		"status": "overwriten",
		"id": "contact_abc123",
		"details": null
}

Example 4: If a contact only had missing fields updated.

JSON

{
		"status": "updated_missing_fields",
		"id": "contact_abc123",
		"details": null
}