contacts

Contact List

List your organization's contacts

get/contacts/

Request

Base URL: https://api.mainstay.com
URL: https://api.mainstay.com/contacts/
Auth: API key in header Authorization

Query parameters

texting_statusstring

Return all contacts with given texting status. Available options: <code>opted-in</code>, <code>opted-out</code>, <code>temp-pause</code>

can_textstring

Return all contacts with given can_text value. <ul><li>Possible true values: True, true, 1</li><li>Possible false values: False, false, 0</li></ul>

customstring

Return all contacts with given value(s) in specified custom field(s). Query Notes<ul><li>The query parameter for all custom fields is <code>custom</code>.</li><li>The value of <code>custom</code> in the URL is: <code>field name|field value</code></li><ul><li>The above translates to: custom field, 'field name', equals 'field value'</li></ul><li>To view all custom fields, send a GET request to https://api.admithub.com/custom_fields or view <a href='https://mascot.admithub.com/contacts/fields'>this page</a>. </li><li>To view all existing values in a field, send a GET request to https://api.admithub.com/custom_values/?field=your-chosen-field. </li><li>To include multiple possible values for a single field (i.e. field equals this OR that), separate values with a comma (<code>,</code> wtih no space). </li><li>To include multiple possible fields (i.e. field #1 equals this AND field #2 equals that), separate multiple <code>custom</code> conditions with an ampersand (<code>&</code> with no space). </li><li>Fields and values with spaces are allowed, but they must be url-encoded, i.e. Field A -> Field%20A </li></ul>Format & Example<ul><li>Format: <code>custom=[field1]|[value1],[value2]&custom=[field2]|[value3],[value4]</code> </li><li>Example: <code>custom=Graduation%20Year|2019,2018&custom=T-shirt%20Size|X%20LG</code></li></ul>

include_test_contactsstring

If true, include test contacts. By default, these contacts are excluded from results.<ul><li>Possible true values: True, true, 1</li><li>Possible false values: False, false, 0</li><li>Default value: False</li><ul>

include_nonpermitted_contactsstring

If true, include contacts with a permittedUser status of False. These are typically contacts who belonged to closed cohorts. By default, these contacts are excluded from results.<ul><li>Possible true values: True, true, 1</li><li>Possible false values: False, false, 0</li><li>Default value: False</li><ul>

modified_sincestring

Return all contacts last modified on or since this date. Timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ.

modified_beforestring

Return all contacts last modified before this date. Timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ.

pageinteger

A page number within the paginated result set.

Response

admithub_idstring

AdmitHub contact ID Can be found in the URL when viewing a contact's page in Mascot Matches <code>id</code>. Will be removed in future API versions. https://app.mainstay.com/contacts/admithub-id

idstring

Mainstay contact ID Matches <code>admithub_id</code>. Can be found in the URL when viewing a contact's page in Mascot https://app.mainstay.com/contacts/admithub-id

crm_idstring

Contact's CRM ID - used as unique identifier in AdmitHub database; <code>null</code> if field is missing from contact record

phonestring

invalid_phoneboolean nullable

previous_phonestring

channelsstring[]

Any of SMS, Slack, and Web Bot institution has enabled.

delivery_failure_countinteger

languagestring

country_calling_codestring

Prefix for phone number which indicates what country the phone number is located within.

conversation_summarystring

AI-generated summary of the conversation with the contact

first_namestring

last_namestring

preferred_namestring

Contact's preferred name. Only writable if blank.

enrollment_idstring

Contact's Enrollment ID - not used as unique identifier in AdmitHub database; <code>null</code> if field is missing from contact record.

emailstring

Contact's Email Address; <code>null</code> if field is missing from contact record.

createdstring date-time

Contact created date (UTC). Matches <code>date_added</code>. Will be removed in future API versions.

date_addedstring date-time

Contact created date (UTC). Matches <code>created</code>.

contactedboolean

<code>true</code> if a contact has been contacted; <code>false</code> if contact has yet to be contacted; field not included in the response if field is missing from contact record.

permitted_user_statusboolean

<code>true</code> if contact is permitted to engage with bot; <code>false</code> if contact is not permitted to engage.

texting_statusstring

Determines whether or not a contact can receive messages.

can_textboolean

If <code>false</code>, the contact cannot be texted; if <code>true</code>, other restrictions may still prevent the contact from being texted. Refer to <code>texting_status</code> field for clarification.

archivedboolean

<code>true</code> if contact is not permitted to engage. <code>false</code> if contact is permitted to engage with bot; inverse of <code>permitted_user_status</code>.

import_labelsstring[]

List of all import labels associated with contact

contact_labelsstring[]

List of all Contact Labels associated with contact

conversation_record_urlstring

URL to view a contact's conversations: https://admithub.mascot.com/conversations/contact's-admithub-id

customobject

Dictionary of contact attributes

channel'twilio' | 'facebook' | 'web' | 'slack'

Channel of communication: web, twilio, slack, or unknown

last_message_atstring date-time

Date/time of last message sent or received by contact.

last_incoming_message_atstring date-time

Date/time of contact's last sent message.

last_outgoing_message_atstring date-time

Date/time of contact's last received message.

last_message_bodystring

Body of last message sent or received by contact.

last_incoming_message_bodystring

Body of last message sent by contact.

last_outgoing_message_bodystring

Body of last message received by contact.

messaging_status_smsstring nullable

Opted In, Paused, or Opted Out for the SMS Channel; <code>null</code> if institution does not use SMS

messaging_status_web_botstring nullable

Opted In, Paused, or Opted Out for the Web Chat Channel; <code>null</code> if institution does not use Web Chat

messaging_status_slackstring nullable

Opted In, Paused, or Opted Out for the Slack Channel; <code>null</code> if institution does not use Slack

script_id_smsstring nullable

ID of the script the contact is currently engaged in on the SMS Channel; <code>null</code> if contact is not in a script or if institution does not use SMS

script_expiration_smsstring nullable

Expiration datetime of the script the contact is currently engaged in on the SMS Channel; <code>null</code> if contact is not in a script or if institution does not use SMS

test_userboolean

last_modified_atstring date-time

Date/time of when contact was last modified by manual updates, imports, or API requests or by any messaging (Campaigns, Live Chat, cold-messaging via SMS or webchat).

webchat_authentication_tokenstring nullable

Token used for authenticating webchat. Rotates every 7-12 days.

Changes

No recorded changes to this operation across all 1 revision of this API.