# New Person

If required, the EmailAddress can be merged into an existing Person as a second step. Note that Person records can only be manipulated if the customer has an AdvancedContacts license.
Similarly, adding an Location to the Person needs to be done using PATCH to the `/persons` endpoint submitting and `locationId` that would have been looked up using GET to the `/locations` endpoint submitting the `organizationId` returned in the response body.

Endpoint: POST /core/persons/insert
Version: 0.0.5
Security: OAuth2

## Request fields (application/json):

  - `emailAddresses` (array)
    Zero or more email addresses that person currently uses, or previously used.
NOT YET IMPLEMENTED.
Requires the TonicDM AdvancedContacts license.
Refer to the `dataQuantity` Request parameter to understand the level of detail returned.

  - `emailAddresses.id` (string)
    Example: 8e8aa42241794371ae9d0ed7b67a8c86

  - `emailAddresses.personId` (string)
    A UUID used to link multiple EmailAddress records together because they belong to the same physical person.
There are no extra fields associated with this UUID. It serves only as a linking mechanism.
Use of `personId` to link multiple EmailAddress records together requires the TonicDM AdvancedContacts license.
    Example: 8e8aa42241794371ae9d0ed7b67a8c86

  - `emailAddresses.status` (string)
    Whether the item is active or inactive in TonicDM. Potentially the item could be (soft) deleted.
    Enum: "active", "inactive", "deleted"

  - `emailAddresses.emailAddress` (string)

  - `emailAddresses.name` (string)
    The person's full name.

  - `emailAddresses.title` (string)
    The person's business title.

  - `emailAddresses.deskphoneCountryCode` (number)
    Numbers only, no spaces or `+` character

  - `emailAddresses.deskphoneNumber` (number)
    Numbers only, no spaces or formatting

  - `emailAddresses.deskphoneExtension` (number)
    Numbers only, no text or formatting

  - `emailAddresses.mobilephoneCountryCode` (number)
    Numbers only, no spaces or `+` character

  - `emailAddresses.mobilephoneNumber` (number)
    Numbers only, no spaces or formatting

  - `emailAddresses.dateActive` (string)
    The date this email address became active. This is used to track the history of email addresses for a person.

REQUIRES the TonicDM AdvancedContacts license.

  - `emailAddresses.dateInactive` (string)
    The date this email address became inactive. This is used to track the history of email addresses for a person. 

REQUIRES the TonicDM AdvancedContacts license.

  - `emailAddresses.isPrime` (boolean)
    Indicates that this email address is the primary email address for this person. 
When displaying a Person, the Prime email address info will be used for their Name, etc.

REQUIRES the TonicDM AdvancedContacts license.

  - `emailAddresses.customerDataWarehouseId` (string)
    The ID of the Person in the Customer's Data Warehouse.
FOR USE BY CUSTOMER. NOT YET IMPLEMENTED.
REQUIRES the TonicDM AdvancedMetrics license.

  - `emailAddresses.customerErpId` (string)
    The ID of the Person in the Customer's ERP system (eg. Deltek Vantagepoint).
FOR USE BY CUSTOMER. NOT YET IMPLEMENTED.
REQUIRES the TonicDM AdvancedMetrics license.

  - `emailAddresses.customerCrmId` (string)
    The ID of the Person in the Customer's CRM system (eg. Deltek Salesforce).
FOR USE BY CUSTOMER. NOT YET IMPLEMENTED.
REQUIRES the TonicDM AdvancedMetrics license.

  - `name` (string, required)
    Display name for the Person (AdvancedContacts).

## Response 201 fields (application/json):

  - `status` (string, required)
    Enum: "success"

  - `data` (array, required)

  - `data.id` (string)
    Example: 8e8aa42241794371ae9d0ed7b67a8c86

  - `data.emailAddresses` (array)
    Zero or more email addresses that person currently uses, or previously used.
NOT YET IMPLEMENTED.
Requires the TonicDM AdvancedContacts license.
Refer to the `dataQuantity` Request parameter to understand the level of detail returned.

  - `data.emailAddresses.personId` (string)
    A UUID used to link multiple EmailAddress records together because they belong to the same physical person.
There are no extra fields associated with this UUID. It serves only as a linking mechanism.
Use of `personId` to link multiple EmailAddress records together requires the TonicDM AdvancedContacts license.
    Example: 8e8aa42241794371ae9d0ed7b67a8c86

  - `data.emailAddresses.brandId` (any)
    Every EmailAddress belongs to a Brand. 
The EmailAddress record carries the personal information and the Brand record carries the corporate information. 
Brand is set automatically by TonicDM based on email address domain and cannot be changed.

  - `data.emailAddresses.datetimeCreated` (string)
    The date and time this email address record was created.

  - `data.emailAddresses.datetimeUpdated` (string)
    The date and time this email address record was last updated.

  - `data.emailAddresses.status` (string)
    Whether the item is active or inactive in TonicDM. Potentially the item could be (soft) deleted.
    Enum: "active", "inactive", "deleted"

  - `data.emailAddresses.emailAddress` (string)

  - `data.emailAddresses.name` (string)
    The person's full name.

  - `data.emailAddresses.title` (string)
    The person's business title.

  - `data.emailAddresses.deskphoneCountryCode` (number)
    Numbers only, no spaces or `+` character

  - `data.emailAddresses.deskphoneNumber` (number)
    Numbers only, no spaces or formatting

  - `data.emailAddresses.deskphoneExtension` (number)
    Numbers only, no text or formatting

  - `data.emailAddresses.mobilephoneCountryCode` (number)
    Numbers only, no spaces or `+` character

  - `data.emailAddresses.mobilephoneNumber` (number)
    Numbers only, no spaces or formatting

  - `data.emailAddresses.emailDeliveryStatus` (string)
    The status of the last email sent to this address. This is updated by the system.
    Enum: "unknown", "delivered", "bounced"

  - `data.emailAddresses.emailType` (string)
    The type of email address. This is set by the system.
    Enum: "business", "personal", "system", "misspelled"

  - `data.emailAddresses.dateActive` (string)
    The date this email address became active. This is used to track the history of email addresses for a person.

REQUIRES the TonicDM AdvancedContacts license.

  - `data.emailAddresses.dateInactive` (string)
    The date this email address became inactive. This is used to track the history of email addresses for a person. 

REQUIRES the TonicDM AdvancedContacts license.

  - `data.emailAddresses.isPrime` (boolean)
    Indicates that this email address is the primary email address for this person. 
When displaying a Person, the Prime email address info will be used for their Name, etc.

REQUIRES the TonicDM AdvancedContacts license.

  - `data.emailAddresses.customerDataWarehouseId` (string)
    The ID of the Person in the Customer's Data Warehouse.
FOR USE BY CUSTOMER. NOT YET IMPLEMENTED.
REQUIRES the TonicDM AdvancedMetrics license.

  - `data.emailAddresses.customerErpId` (string)
    The ID of the Person in the Customer's ERP system (eg. Deltek Vantagepoint).
FOR USE BY CUSTOMER. NOT YET IMPLEMENTED.
REQUIRES the TonicDM AdvancedMetrics license.

  - `data.emailAddresses.customerCrmId` (string)
    The ID of the Person in the Customer's CRM system (eg. Deltek Salesforce).
FOR USE BY CUSTOMER. NOT YET IMPLEMENTED.
REQUIRES the TonicDM AdvancedMetrics license.

  - `metadata` (object, required)
    Present on every JSON response. For non-paginated operations, `page` will be 1, `total_pages` will be 1,
and `total_records` equal to the number of elements in `data`.

  - `metadata.timestamp` (string, required)

  - `metadata.correlation_id` (string, required)

  - `metadata.page` (integer, required)

  - `metadata.total_pages` (integer, required)

  - `metadata.total_records` (integer, required)

## Response 400 fields (application/json):

  - `status` (string, required)
    Enum: "fail", "error"

  - `error` (object, required)

  - `error.code` (string, required)
    Example: VALIDATION_ERROR

  - `error.message` (string, required)
    Example: Invalid input

  - `metadata` (object, required)
    Present on every JSON response. For non-paginated operations, `page` will be 1, `total_pages` will be 1,
and `total_records` equal to the number of elements in `data`.

  - `metadata.timestamp` (string, required)

  - `metadata.correlation_id` (string, required)

  - `metadata.page` (integer, required)

  - `metadata.total_pages` (integer, required)

  - `metadata.total_records` (integer, required)

## Response 401 fields (application/json):

  - `status` (string, required)
    Enum: "fail", "error"

  - `error` (object, required)

  - `error.code` (string, required)
    Example: VALIDATION_ERROR

  - `error.message` (string, required)
    Example: Invalid input

  - `metadata` (object, required)
    Present on every JSON response. For non-paginated operations, `page` will be 1, `total_pages` will be 1,
and `total_records` equal to the number of elements in `data`.

  - `metadata.timestamp` (string, required)

  - `metadata.correlation_id` (string, required)

  - `metadata.page` (integer, required)

  - `metadata.total_pages` (integer, required)

  - `metadata.total_records` (integer, required)

## Response 403 fields (application/json):

  - `status` (string, required)
    Enum: "fail", "error"

  - `error` (object, required)

  - `error.code` (string, required)
    Example: VALIDATION_ERROR

  - `error.message` (string, required)
    Example: Invalid input

  - `metadata` (object, required)
    Present on every JSON response. For non-paginated operations, `page` will be 1, `total_pages` will be 1,
and `total_records` equal to the number of elements in `data`.

  - `metadata.timestamp` (string, required)

  - `metadata.correlation_id` (string, required)

  - `metadata.page` (integer, required)

  - `metadata.total_pages` (integer, required)

  - `metadata.total_records` (integer, required)

## Response 404 fields (application/json):

  - `status` (string, required)
    Enum: "fail", "error"

  - `error` (object, required)

  - `error.code` (string, required)
    Example: VALIDATION_ERROR

  - `error.message` (string, required)
    Example: Invalid input

  - `metadata` (object, required)
    Present on every JSON response. For non-paginated operations, `page` will be 1, `total_pages` will be 1,
and `total_records` equal to the number of elements in `data`.

  - `metadata.timestamp` (string, required)

  - `metadata.correlation_id` (string, required)

  - `metadata.page` (integer, required)

  - `metadata.total_pages` (integer, required)

  - `metadata.total_records` (integer, required)

## Response 429 fields (application/json):

  - `status` (string, required)
    Enum: "fail", "error"

  - `error` (object, required)

  - `error.code` (string, required)
    Example: VALIDATION_ERROR

  - `error.message` (string, required)
    Example: Invalid input

  - `metadata` (object, required)
    Present on every JSON response. For non-paginated operations, `page` will be 1, `total_pages` will be 1,
and `total_records` equal to the number of elements in `data`.

  - `metadata.timestamp` (string, required)

  - `metadata.correlation_id` (string, required)

  - `metadata.page` (integer, required)

  - `metadata.total_pages` (integer, required)

  - `metadata.total_records` (integer, required)

## Response 500 fields (application/json):

  - `status` (string, required)
    Enum: "fail", "error"

  - `error` (object, required)

  - `error.code` (string, required)
    Example: VALIDATION_ERROR

  - `error.message` (string, required)
    Example: Invalid input

  - `metadata` (object, required)
    Present on every JSON response. For non-paginated operations, `page` will be 1, `total_pages` will be 1,
and `total_records` equal to the number of elements in `data`.

  - `metadata.timestamp` (string, required)

  - `metadata.correlation_id` (string, required)

  - `metadata.page` (integer, required)

  - `metadata.total_pages` (integer, required)

  - `metadata.total_records` (integer, required)