contacts

Contact Bulk Operation

Create/update many contacts by sending multiple contacts' data in a JSON-formatted request body. See an example request in the 'Request Body Parameters' section of the introductory documentation above. This endpoint will return a job_id to be used in the Contacts Bulk Check Operation Endpoint below.

post/contacts/bulk/

Request

Base URL: https://api.mainstay.com
URL: https://api.mainstay.com/contacts/bulk/
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>

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>

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 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.

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

Deprecated. Use <code>messaging_status_sms</code>, etc. instead. <code>true</code> if a contact can receive messages from the bot <code>false</code> if a contact cannot receive messages from the bot Note: 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

idstring

Unique per contact. Mainstay ID

admithub_idstring

Response

Created

job_idstring required

Changes

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