{"_id":"570290813dd5ef2d008244d3","__v":5,"category":{"_id":"55ad4d1933616a0d00599d2f","project":"55843604fd8d910d007b9502","version":"558444ceafccfd0d00fcb2bb","pages":["55ad4fa424cf160d00135866","55ad4fb46aadf20d0015b77c","55ad4fc724cf160d00135868","55ad4fdb24cf160d0013586a","55ad4ff424cf160d0013586c","55ad500824cf160d0013586e","55ad50206aadf20d0015b77e","55ad503a6aadf20d0015b780","5633d0277b56ae0d0025a057","56e333d0941515170011da12"],"__v":10,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-07-20T19:33:45.600Z","from_sync":false,"order":15,"slug":"mailing-lists","title":"Insights Platform Contacts"},"editedParams":true,"version":{"_id":"558444ceafccfd0d00fcb2bb","forked_from":"55843604fd8d910d007b9505","project":"55843604fd8d910d007b9502","__v":46,"createdAt":"2015-06-19T16:35:26.435Z","releaseDate":"2015-06-19T16:35:26.435Z","categories":["558444cfafccfd0d00fcb2bc","558444cfafccfd0d00fcb2bd","55ad4ce733616a0d00599d2e","55ad4cef6aadf20d0015b764","55ad4cf36aadf20d0015b765","55ad4cfb24cf160d0013584f","55ad4d0024cf160d00135850","55ad4d0a24cf160d00135851","55ad4d0d24cf160d00135852","55ad4d126aadf20d0015b766","55ad4d1624cf160d00135853","55ad4d1933616a0d00599d2f","55ad4d2233616a0d00599d30","55ad4d2e24cf160d00135854","55d35b6bf77e6d0d00b1b092","55d3649a0168850d0073f14a","55d366d40168850d0073f15a","55d37fcff77e6d0d00b1b13f","55d383e50168850d0073f1e1","55d3ac26c336ec0d007c2251","55d3c51cb2330119009c31db","55d3c59bfe37111900e536f3","55d3c5a7fe37111900e536f4","55d3c5b4fe37111900e536f5","55d3c5d4fe37111900e536f6","55d3c5d6b2330119009c31df","55d3c5d71f478b170077c164","55d3c687b2330119009c31e4","55d3c6a4fe37111900e536f9","55d3c6befe37111900e536fa","55d3c6e8d2c66f0d00497f93","55d49dcfd7c16b2d007de905","55d4ca8f5082980d0009c79b","55d4cab9c95a3d2f0069ad3d","55d4d279c95a3d2f0069ad60","55d4d9355082980d0009c7e1","55d4f6b5988e130d000b3eb1","55d64dc8e60a2f0d00b88ecb","5627ca43fcbbc621004ec07d","56c64a0d8f98b50d0012c37c","56f1b8b13eb62a34003ea041","56f1b9df4476fb2200795e8c","57f6907dca5e5d1700039ae9","591dd06ca266c423002ec4ca","59234825e465c11900922518","5936f82eaa591e0027638d57","59972f54fd7078001992c136"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"","version_clean":"3.0.0","version":"3"},"editedParams2":true,"user":"558435c2fb52ee0d0015d190","parentDoc":null,"project":"55843604fd8d910d007b9502","updates":["588d8b7c1413030f002798b2"],"next":{"pages":[],"description":""},"createdAt":"2016-04-04T16:04:17.758Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[{"name":"","status":200,"language":"json","code":"{\n  \"result\": {\n    \"id\": \"PGRS_cZSTWTMcmNd9yRv\"\n  },\n  \"meta\": {\n    \"httpStatus\": \"200 - OK\"\n  }\n}"}]},"settings":"","examples":{"codes":[{"name":"cURL File Upload","code":"curl 'https://yourdatacenterid.qualtrics.com/API/v3/mailinglists/ML_123456789/contactimports' \\\n-X POST \\\n-H 'X-API-TOKEN: yourapitoken' \\\n-F 'file=:::at:::/path/to/contacts.json'","language":"curl"},{"code":"curl 'https://yourdatacenterid.qualtrics.com/API/v3/mailinglists/ML_123456789/contactimports' \\\n-X POST \\\n-H 'X-API-TOKEN: yourapitoken' \\\n-H 'Content-Type: application/json' \\\n-d '{\n      \"contacts\": [\n        {\n          \"id\": \"MLRP_123456789012345\", \n          \"firstName\": \"ExampleFirstName\",\n          \"lastName\": \"ExampleLastName\",\n          \"email\": \"example@example.com\",\n          \"language\": \"SP\",\n          \"unsubscribed\": 1,\n          \"externalReference\":\"Example\",\n          \"embeddedData\": {\n            \"ExampleField1\":\"example_field_val_1\", \n            \"ExampleField2\":\"example_field_val_2\"\n        },\n        {\n          \"id\": \"MLRP_543210987654321\",\n          \"firstName\": \"ExampleFirstName_2\",\n          \"lastName\": \"ExampleLastName_2\",\n          \"email\": \"example_2@example.com\",\n          \"language\": \"EN\",\n          \"unsubscribed\": 0,\n          \"externalReference\":\"Example\",\n          \"embeddedData\": {\n            \"ExampleField1\":\"example_field_val_1.2\", \n            \"ExampleField2\":\"example_field_val_2.2\"\n        }\n      ]\n    }'","name":"cURL Request Body","language":"curl"}]},"method":"post","auth":"required","params":[{"_id":"55ad71aa33616a0d00599e01","ref":"","in":"path","required":true,"desc":"ID of the mailingList into which contacts will be imported (found <a href=\"https://www.qualtrics.com/support/integrations/api-integration/finding-qualtrics-ids/\" target=\"_blank\">in Qualtrics IDs</a> )","default":"","type":"string","name":"mailingListId"},{"_id":"5903c223cb65be2f00f5f01e","ref":"","in":"header","required":true,"desc":"Must be **application/json** or **multipart/form-data**. Depends on how the request content is supplied. If using cURL with **-F**, this header is not needed.","default":"","type":"string","name":"Content-Type"},{"_id":"5907663e2841992500dc46dc","ref":"","in":"body","required":false,"desc":"A JSON array of mailing list contacts. This JSON array can be uploaded via a file or placed in the request body (must be keyed under **contacts**). You **cannot** provide both a file upload and a request body. See notes below.","default":"","type":"array_object","name":"contacts"}],"url":"/v:version/mailinglists/:mailingListId/contactimports"},"isReference":false,"order":11,"body":"[block:callout]\n{\n  \"type\": \"danger\",\n  \"title\": \"The JSON content (in a file or the request body) size is limited to 5MB.\",\n  \"body\": \"If more contacts need to be imported, they should be imported with subsequent calls.\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"danger\",\n  \"title\": \"Naming your upload.\",\n  \"body\": \"When using cURL -F, the full path to your file must be prefixed with **file=@**. If this prefix does not exist, you will receive an error.\"\n}\n[/block]\nThe API request requires a JSON array of JSON objects - where each object represents one mailing list contact. As mentioned above, this JSON array can be provided in the request body or be provided in a **.json** file.\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Content-Type request header\",\n  \"body\": \"If the JSON array of contacts is provided in the request body, the **Content-Type** must be **application/json**.\\n\\nIf the JSON array of contacts is provided via a file upload, the **Content-Type** must be **multipart/form-data**. [-F](https://curl.haxx.se/docs/manpage.html#-F) in cURL automatically applies the **multipart/form-data** content type header.\"\n}\n[/block]\nEach contact object accepts the following optional fields: **id**, **firstName**, **lastName**, **email**, **unsubscribed**, **externalReference**, and **embeddedData**. The **embeddedData** field consists of a JSON object with user defined keys and values. \n\nExample JSON array:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"/* Remove all comments before testing*/\\n[\\n  {\\n    \\\"id\\\": \\\"MLRP_123456789012345\\\", /* If included, the contact with this id will be updated. */\\n    \\\"firstName\\\": \\\"ExampleFirstName\\\",\\n    \\\"lastName\\\": \\\"ExampleLastName\\\",\\n    \\\"email\\\": \\\"example@example.com\\\",\\n    \\\"language\\\": \\\"SP\\\",\\n    \\\"unsubscribed\\\":1, /* Set to 1 to opt-out the contact */\\n    \\\"externalReference\\\":\\\"Example\\\",\\n    \\\"embeddedData\\\": {\\\"ExampleField1\\\":\\\"example_field_val_1\\\", \\\"ExampleField2\\\":\\\"example_field_val_2\\\"}\\n  }\\n]\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nThis call will return an **importId** that can be used to check on the status of the import via [Get Contacts Import Progress](doc:get-contacts-import).\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Try It Out Feature Limitation\",\n  \"body\": \"Unfortunately, this feature will not let you upload files. Our suggestion is to use the Postman app. If you are on a Windows machine, you should download the application from getpostman.com.\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Deprecation Notes\",\n  \"body\": \"If this API is used with **-F 'contacts=@/path/...**, the API will still execute. However it is recommended to switch to **-F 'file=@/path/...**.\"\n}\n[/block]","excerpt":"Imports contacts into a mailing list","slug":"create-contacts-import","type":"endpoint","title":"Create Contacts Import"}

postCreate Contacts Import

Imports contacts into a mailing list

Definition

{{ api_url }}{{ page_api_url }}

Parameters

Path Params

mailingListId:
required
string
ID of the mailingList into which contacts will be imported (found <a href="https://www.qualtrics.com/support/integrations/api-integration/finding-qualtrics-ids/" target="_blank">in Qualtrics IDs</a> )

Body Params

contacts:
array of objects
A JSON array of mailing list contacts. This JSON array can be uploaded via a file or placed in the request body (must be keyed under **contacts**). You **cannot** provide both a file upload and a request body. See notes below.

Headers

Content-Type:
required
string
Must be **application/json** or **multipart/form-data**. Depends on how the request content is supplied. If using cURL with **-F**, this header is not needed.

Examples


Result Format


Documentation

[block:callout] { "type": "danger", "title": "The JSON content (in a file or the request body) size is limited to 5MB.", "body": "If more contacts need to be imported, they should be imported with subsequent calls." } [/block] [block:callout] { "type": "danger", "title": "Naming your upload.", "body": "When using cURL -F, the full path to your file must be prefixed with **file=@**. If this prefix does not exist, you will receive an error." } [/block] The API request requires a JSON array of JSON objects - where each object represents one mailing list contact. As mentioned above, this JSON array can be provided in the request body or be provided in a **.json** file. [block:callout] { "type": "warning", "title": "Content-Type request header", "body": "If the JSON array of contacts is provided in the request body, the **Content-Type** must be **application/json**.\n\nIf the JSON array of contacts is provided via a file upload, the **Content-Type** must be **multipart/form-data**. [-F](https://curl.haxx.se/docs/manpage.html#-F) in cURL automatically applies the **multipart/form-data** content type header." } [/block] Each contact object accepts the following optional fields: **id**, **firstName**, **lastName**, **email**, **unsubscribed**, **externalReference**, and **embeddedData**. The **embeddedData** field consists of a JSON object with user defined keys and values. Example JSON array: [block:code] { "codes": [ { "code": "/* Remove all comments before testing*/\n[\n {\n \"id\": \"MLRP_123456789012345\", /* If included, the contact with this id will be updated. */\n \"firstName\": \"ExampleFirstName\",\n \"lastName\": \"ExampleLastName\",\n \"email\": \"example@example.com\",\n \"language\": \"SP\",\n \"unsubscribed\":1, /* Set to 1 to opt-out the contact */\n \"externalReference\":\"Example\",\n \"embeddedData\": {\"ExampleField1\":\"example_field_val_1\", \"ExampleField2\":\"example_field_val_2\"}\n }\n]", "language": "json" } ] } [/block] This call will return an **importId** that can be used to check on the status of the import via [Get Contacts Import Progress](doc:get-contacts-import). [block:callout] { "type": "warning", "title": "Try It Out Feature Limitation", "body": "Unfortunately, this feature will not let you upload files. Our suggestion is to use the Postman app. If you are on a Windows machine, you should download the application from getpostman.com." } [/block] [block:callout] { "type": "warning", "title": "Deprecation Notes", "body": "If this API is used with **-F 'contacts=@/path/...**, the API will still execute. However it is recommended to switch to **-F 'file=@/path/...**." } [/block]

User Information

Try It Out

post
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}