Contact

post

https://api.marketcircle.net/v1/contacts

Create a new contact

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

See Contact for a list of attributes which are supported for contacts. Only attributes marked as Read-Write can be set using this endpoint.

Ownership

The creator of the contact will automatically be set to the user performing the request. However, a contact also has an owner, which is the user responsible for the contact. It defaults to the user making the request. See the ownership page for more details.

📘
Categories and Keywords
Categories and keywords are serialized using the category/keyword name instead of URL references. If you name a category or keyword that does not already exist, it will be created automatically.

Response

A successful request returns 201 Created with the new contact's reference:

{ "location": "/v1/contacts/1000" }

Validation

Various validations are run on the supplied contact object. If any validations fail, then an HTTP 400 Bad Request response will be returned. The body lists the failed validations for each attribute:

{ "first_name": [{ "error": "too_long", "count": 256 }] }

Body Params

prefix

string

Salutation, e.g. "Mr." or "Dr." (max 128 characters).

individual_salutation

string

How to address the contact in letters, e.g. "Dear John" (max 512 characters).

first_name

string

First name (max 256 characters).

middle_name

string

Middle name(s) (max 256 characters).

last_name

string

Last name (max 256 characters).

suffix

string

Name suffix, e.g. "Jr." or "PhD" (max 64 characters).

alias

string

Legal alias (max 512 characters).

nickname

string

Casual nickname (max 256 characters).

birthday

date

Birthday as YYYY-MM-DD. Use 0000 as the year when it is unknown, e.g. 0000-06-03.

anniversary

date

Anniversary as YYYY-MM-DD. Use 0000 as the year when it is unknown.

flagged

boolean

Whether the contact is flagged.

tagline

string

Tagline (max 512 characters).

hobbies

string

Hobbies (max 1024 characters).

category

string

Category name. Created if it does not exist. Send null or "" to clear.

keywords

array of strings

List of keyword names (max 64). Keywords that do not exist are created. On update, an array replaces the whole list. Send {"add": [...], "remove": [...]} instead to change only some entries.

keywords

extra_fields

object

Extra (custom) field values, keyed by the field's default identifier even if it has been renamed. Each value is an object with a value key. Fields you leave out are not changed; send null or {} to clear all of them.

emails

array of objects

Email addresses of the contact. On update, an array replaces the whole list. Send {"add": [...], "remove": [...]} instead to change only some entries.

emails

urls

array of objects

Websites of the contact. On update, an array replaces the whole list. Send {"add": [...], "remove": [...]} instead to change only some entries.

urls

social_profiles

array of objects

Social profiles of the contact. On update, an array replaces the whole list. Send {"add": [...], "remove": [...]} instead to change only some entries.

social_profiles

phone_numbers

array of objects

Phone numbers of the contact. On update, an array replaces the whole list. Send {"add": [...], "remove": [...]} instead to change only some entries.

phone_numbers

addresses

array of objects

Postal addresses of the contact. On update, an array replaces the whole list. Send {"add": [...], "remove": [...]} instead to change only some entries.

addresses

details

string

Short notes about the contact (max 8000 characters). For longer text, link a note.

companies

array of objects

Companies the contact works for (roles). On update, an array replaces the whole list. Send {"add": [...], "remove": [...]} instead to change only some entries.

companies

opportunities

array of objects

Opportunities the contact is involved in (roles). On update, an array replaces the whole list. Send {"add": [...], "remove": [...]} instead to change only some entries.

opportunities

projects

array of objects

Projects the contact is involved in (roles). On update, an array replaces the whole list. Send {"add": [...], "remove": [...]} instead to change only some entries.

projects

contacts

array of objects

Other contacts this contact is related to. On update, an array replaces the whole list. Send {"add": [...], "remove": [...]} instead to change only some entries.

contacts

appointments

array of objects

Appointments linked to the contact. On update, an array replaces the whole list. Send {"add": [...], "remove": [...]} instead to change only some entries.

appointments

groups

array of objects

Groups linked to the contact. On update, an array replaces the whole list. Send {"add": [...], "remove": [...]} instead to change only some entries.

groups

notes

array of objects

Notes linked to the contact. On update, an array replaces the whole list. Send {"add": [...], "remove": [...]} instead to change only some entries.

notes

tasks

array of objects

Tasks linked to the contact. On update, an array replaces the whole list. Send {"add": [...], "remove": [...]} instead to change only some entries.

tasks

forms

array of objects

Forms linked to the contact. On update, an array replaces the whole list. Send {"add": [...], "remove": [...]} instead to change only some entries.

forms

email_messages

array of objects

Emails to link to the contact. Write-only: linked emails are not returned on the contact; use GET /v1/{type}/{id}/emails instead. On update, an array replaces the whole list. Send {"add": [...], "remove": [...]} instead to change only some entries.

email_messages

owner

string

Reference to the user responsible for the contact, e.g. /v1/users/1000. Defaults to the user making the request.

Responses

Ownership

Categories and Keywords

Response

Validation

201201 Created

400400 Bad Request