contacts

Contact Update

Update a single contact, matching on CRM ID, phone, or AdmitHub ID

put/contacts/{id}/

Request

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

Path parameters

idstring required

CRM ID, phone, or AdmitHub ID of contact <ul><li>AdmitHub ID can be found in the URL when viewing a single contact's page in Mascot</li><ul><li>https://mascot.admithub.com/contacts/admithub-contact-id</li></ul><li>If using phone as path parameter, it must be exactly 10 digits with no spaces or non-numerical characters</li></ul>

Query parameters

texting_statusstring

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

customstring

Return all contacts with given value(s) in specified custom field(s). <br /><br /><strong>Query Notes</strong><ul><li>The query parameter for <em>all</em> 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><strong>Format & Example</strong><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>

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>

include_test_contactsstring

If <u>true</u>, 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 <u>true</u>, 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. <br />Timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ.

modified_beforestring

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

Request body

messaging_status_smsstring

Opted In, Paused, or Opted Out for the SMS Channel; <code>null</code> if institution does not use SMS; Accepted values: 'opted-in', 'opted-out', 'opted in', 'opted out', 'paused'; case-insensitive

messaging_status_web_botstring

Opted In, Paused, or Opted Out for the Web Chat Channel; <code>null</code> if institution does not use Web Chat; Accepted values: 'opted-in', 'opted-out', 'opted in', 'opted out', 'paused'; case-insensitive

messaging_status_slackstring

Opted In, Paused, or Opted Out for the Slack Channel; <code>null</code> if institution does not use Slack; Accepted values: 'opted-in', 'opted-out', 'opted in', 'opted out', 'paused'; case-insensitive

phonestring

Unique per contact, 10 digits w/ no spaces or non-numerical characters

country_calling_codestring

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

first_namestring
last_namestring
preferred_namestring
languagestring
crm_idstring

Contact's CRM ID - used as unique identifier in AdmitHub database

emailstring

Contact's email address

enrollment_idstring

Contact's Enrollment ID - not used as unique identifier in AdmitHub database

import_labelsstring[]

Comma-separated list of quote-wrapped labels in square brackets, e.g. ['transfer-student', 'scholar athlete']

customobject
<ul><li>Dictionary of custom fields/values to be added to contact records.</li><li>Values can be of type string, boolean, or number.</li><li>View available custom fields by sending a GET request to <a href='https://api.admithub.com/custom_fields'>https://api.admithub.com/custom_fields</a> or by viewing <a href='https://mascot.admithub.com/contacts/fields'>this page</a>.</li><li>Adding new fields via API request is not permitted. Values cannot exceed length of 1000 characters.</li><li>E.g.: {'t-shirt-size': 'sm', 'quiet dorm': false, 'account balance': 100}</li></ul>
can_textboolean

<strong>Deprecated.</strong> Use <code>messaging_status_sms</code>, etc. instead.<br /><code>true</code> if a contact can receive messages from the bot<br /><code>false</code> if a contact cannot receive messages from the bot<br /><u>Note</u>: This value cannot be changed from <code>false</code> to <code>true</code> via API request.

permitted_userboolean

<code>true</code> if contact is permitted to engage with bot; <code>false</code> if contact is not permitted to engage. This field is an indicator of a contact's archived status.

archivedboolean

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

sourcestring

Only necessary on requests sent via integrations

admithub_idstring

Response

Created

admithub_idstring

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

idstring

Mainstay contact ID<br />Matches <code>admithub_id</code>.<br />Can be found in the URL when viewing a contact's page in Mascot<br />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.