# Get Persons

Gets data on one or more Persons. A Person is a collection of one or more EmailAddresses.
If called with no parameters (ie. `/persons`) it will return data for all Persons in no specific order.
If called with just the `dataQuantity=idOnly` parameter (ie. `/persons?dataQuantity=idOnly`), it will return just the `id` of the selected people.
A specific set of persons' data can be returned by providing the `filterIds` parameter with an array of Person `id` (ie. `/persons?filterIds={personId},{personId}`).
If caching the Person data on the client side, the `dataQuantity=idOnly` option can be chosen to get the list of UUIDs that match the filtering/sorting/paging requirements, with the Person data coming from your client side cache, having been retrieved by providing the `filterIds` parameter with an array of `id`.
Note that staff in the user's own Organization are Persons just like their Contacts. Mailboxes are handled separately from Persons or EmailAddresses (refer to the Correspondence module for Mailbox endpoints).

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

## Request fields (application/json):

  - `searchQuery` (string)
    A JSON-encoded string containing the query options.

  - `filterIds` (array)
    Returns data for the specified UUIDs. If this filter is specifed, all other filters will be ignored.

  - `filterOrganizationIds` (array)
    Returns data for the specified Organization UUIDs

  - `filterStatuses` (array)
    Provide the values in an array. If more than one value is given, they will be combined with OR.
If no value is supplied, `active` is assumed.

  - `filterDisciplineIds` (array)
    provide the UUIDs of one or more disciplines separated by comma (no spaces). If more than one filter is given, they will be combined with AND.

  - `filterLocationIds` (array)
    Provide the UUIDs of one or more locations separated by comma (no spaces). If more than one filter is given, they will be combined with AND.

  - `dataQuantity` (string)
    If caching data on the client side, the `dataQuantity=idOnly|basic|complete` option can be passed to manage the completeness of the data received and therefore rate limiting.
    Enum: "idOnly", "basic", "complete"

  - `pageSize` (integer)
    The number of results to return per page

  - `pageNumber` (integer)
    Which page of the results to return

  - `sortByPersons` (string)
    The field by which to sort the results
    Enum: "name", "email", "title", "location"

  - `sortDirection` (string)
    The sort direction for the results
    Enum: "asc", "desc"

## Response 200 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)