Create Bulk Entity Import
POST {{baseUrl}}/directories/:directoryId/imports
Create a Bulk Entity Import.
Private Preview Functionality
This API is not yet generally available. It is available as part of Early Access to receive feedback. Be aware that there may be significant changes to this API with short notice until the time that the API is made Generally Available.
See the following examples of import jobs: * Creating a contact with email as dedupe field * Updating a contact with ID * Updating a contact through email * Upsert contact and add to list * Add existing contact to two lists * Update existing contact in list using ID * Update existing contact in list using dedupe fields * New transaction * New transaction to upserted contact * Upsert transaction and add to batch with contact with dedupe fields * Update to existing transaction and existing contact with ID * Update to existing transaction with extRef * Update to existing transaction and contact with extRef and dedeup fields * New transaction with enrichment * Upsert enrichment with transaction using extRef * Upsert a contact with a transaction and an enrichment—adding to a batch and list * Bulk upsert contacts and add to a list
Creating a contact with email as dedupe field
Request
{
"contacts": [
{
"refId": "new_contact",
"firstName": "Bob",
"lastName": "Smith",
"email": "bob.smith@example.com"
}
]
}
Response
200 Successful Bulk Entities Import
{
"entities": [
{
"refId": "new_contact",
"type": "INSERT",
"id": "CID_0Dpr6XqaJjKvJQ2"
}
]
}
Updating a contact with ID
Request
{
"contacts": [
{
"id": "CID_000H1GQiVYrqmJ7",
"refId": "updated_contact",
"firstName": "newFirstName",
"language": "EN"
}
]
}
Response
200 Successful Bulk Entities Import
{
"entities": [
{
"refId": "updated_contact",
"type": "UPDATE",
"id": "CID_000H1GQiVYrqmJ7"
}
]
}
Updating a contact through email
Request
{
"contacts": [
{
"firstName": "newFirstName",
"refId": "updated_contact",
"email": "bob.smith@example.com",
"language": "EN"
}
]
}
Response
200 Successful Bulk Entities Import
{
"entities": [
{
"refId": "updated_contact",
"type": "UPDATE",
"id": "CID_000H1GQiVYrqmJ7"
}
]
}
Upsert contact and add to list
Request
{
"contacts": [
{
"email": "bob.smith@example.com",
"refId": "upsert_contact",
"phone": "555-555-5555",
"listMemberships": [
{
"refId": "list1",
"listId": "CG_2X4YDnxnprNKdvi",
"unsubscribed": false
}
]
}
]
}
Response
200 Successful Bulk Entities Import
{
"entities": [
{
"refId": "upsert_contact",
"type": "UPDATE",
"id": "CID_000H1GQiVYrqmJ7"
},
{
"refId": "list1",
"id": "CG_2X4YDnxnprNKdvi".
"type": "INSERT"
}
]
}
Add existing contact to two lists
Request
{
"contacts": [
{
"id": "CID_000H1GQiVYrqmJ7",
"listMemberships": [
{
"refId": "list1",
"listId": "CG_2X4YDnxnprNKdvi",
"unsubscribed": false
},
{
"refId": "list2",
"listId": "CG_rwv2hy7d4wcq44t",
"unsubscribed": true,
"unsubscribedDate": "2022-03-07T19:04:11Z"
}
]
}
]
}
Response
200 Successful Bulk Entities Import
{
"entities": [
{
"refId": "list1",
"id": "CG_2X4YDnxnprNKdvi".
"type": "INSERT"
},
{
"refId": "list2",
"ID": "CG_rwv2hy7d4wcq44t",
"type": "INSERT"
}
]
}
Update existing contact in list using ID
Request
{
"contacts": [
{
"id": "CID_000H1GQiVYrqmJ7",
"listMemberships": [
{
"refId": "list1",
"listId": "CG_2X4YDnxnprNKdvi",
"unsubscribed": true
}
]
}
]
}
Response
200 Successful Bulk Entities Import
{
"entities": [
{
"refId": "list1",
"id": "CG_2X4YDnxnprNKdvi",
"type": "UPDATE"
}
]
}
Update existing contact in list using dedupe fields
Request
{
"contacts": [
{
"refId": "existing_contact",
"email": "bob.smith@example.com",
"listMemberships": [
{
"refId": "list1",
"listId": "CG_2X4YDnxnprNKdvi",
"unsubscribed": true
}
]
}
]
}
Response
200 Successful Bulk Entities Import
{
"entities": [
{
"refId": "existing_contact",
"type": "UPDATE"
},
{
"refId": "list1",
"id": "CG_2X4YDnxnprNKdvi",
"type": "UPDATE"
}
]
}
New transaction
Request
{
"contacts": [
{
"id": "CID_000H1GQiVYrqmJ7",
"transactions": [
{
"refId": "new_transaction",
"enrichments": [],
"transactionDate": "2022-03-07T19:04:11Z",
"data": {
"order_number": 23531
}
"extRef": "4980e00c-df34-4d1c-a6b3-79a79ac3d72c",
"contactListId": "CG_2X4YDnxnprNKdvi"
}
]
}
]
}
Response
200 Successful Bulk Entities Import
{
"entities": [
{
"refId": "new_transaction",
"type": "INSERT"
}
]
}
New transaction to upserted contact
Request
{
"contacts": [
{
"refId": "upserted_contact",
"email": "bob.smith@example.com",
"transactions": [
{
"refId": "new_transaction",
"transactionDate": "2022-03-07T19:04:11Z",
"data": {
"order_number": 23531
},
"extRef": "4980e00c-df34-4d1c-a6b3-79a79ac3d72c",
"contactListId": "CG_2X4YDnxnprNKdvi",
"enrichments": []
}
]
}
]
}
Response
200 Successful Bulk Entities Import
{
"entities": [
{
"refId": "upserted_contact",
"type": "UPDATE"
},
{
"refId": "new_transaction",
"type": "INSERT"
}
]
}
Upsert transaction and add to batch with contact with dedupe fields
Request
{
"contacts": [
{
"refId": "upserted_contact",
"email": "bob.smith@example.com",
"transactions": [
{
"refId": "new_transaction",
"extRef": "4980e00c-df34-4d1c-a6b3-79a79ac3d72c",
"batches": [
{
"batchId": "BT_ufpqo545ohxslc7",
"refId": "batch1"
}
],
"enrichments": []
}
]
}
]
}
Response
200 Successful Bulk Entities Import
{
"entities": [
{
"refId": "upserted_contact",
"type": "UPDATE"
},
{
"refId": "new_transaction",
"type": "INSERT"
},
{
"refId": "batch1",
"type": "INSERT"
}
]
}
Update to existing transaction and existing contact with ID
Request
{
"contacts": [
{
"id": "CID_000H1GQiVYrqmJ7",
"transactions": [
{
"id": "CTR_BybqCDSZTHnL0Y1",
// refId is still required because we are updating the transaction
"refId": "updated_transaction",
"data": {
"color": "red"
},
"enrichments": []
}
]
}
]
}
Response
200 Successful Bulk Entities Import
{
"entities": [
{
"refId": "updated_transaction",
"type": "UPDATE"
}
]
}
Update to existing transaction with extRef
Request
{
"contacts": [
{
"id": "CID_000H1GQiVYrqmJ7",
"transactions": [
{
"extRef": "4980e00c-df34-4d1c-a6b3-79a79ac3d72c",
"refId": "updated_transaction",
"data": {
"color": "blue"
},
"enrichments": []
}
]
}
]
}
Response
200 Successful Bulk Entities Import
{
"entities": [
{
"refId": "updated_transaction",
"type": "UPDATE"
}
]
}
Update to existing transaction and contact with extRef and dedeup fields
Request
{
"contacts": [
{
"refId": "upserted_contact",
"email": "bob.smith@example.com",
"transactions": [
{
"extRef": "4980e00c-df34-4d1c-a6b3-79a79ac3d72c",
"refId": "updated_transaction",
"data": {
"color": "green"
},
"enrichments": []
}
]
}
]
}
Response
200 Successful Bulk Entities Import
{
"entities": [
{
"refId": "upserted_contact",
"type": "UPDATE"
},
{
"refId": "updated_transaction",
"type": "UPDATE"
}
]
}
New transaction with enrichment
Request
{
"contacts": [
{
"id": "CID_000H1GQiVYrqmJ7",
"transactions": [
{
"refId": "new_transaction",
"transactionDate": "2022-03-07T19:04:11Z",
"data": {
"order_number": 23531
},
"contactListId": "CG_2X4YDnxnprNKdvi",
"enrichments": [
{
"refId": "enrichment1",
"source": {
"context": {
"surveyId": "SV_abFJEwtZF9NyFtH",
"questionId": "QID1",
"responseId": "R_Ggmm1Bf6rhogiBd"
},
"provider": "response-engine"
},
"metric": {
"type": "gauge",
"field": "ses://nps",
"numValue": 3,
"date": "2022-03-07T19:04:11Z"
}
}
]
}
]
}
]
}
Response
200 Successful Bulk Entities Import
{
"entities": [
{
"refId": "new_transaction",
"type": "INSERT"
},
{
"refId": "enrichment1",
"type": "INSERT"
}
]
}
Upsert enrichment with transaction using extRef
Request
{
"contacts": [
{
"id": "CID_000H1GQiVYrqmJ7",
"transactions": [
{
"refId": "new_transaction",
"extRef": "4980e00c-df34-4d1c-a6b3-79a79ac3d72c",
"enrichments": [
{
"refId": "enrichment1",
"source": {
"context": {
"surveyId": "SV_abFJEwtZF9NyFtH",
"questionId": "QID1",
"responseId": "R_Ggmm1Bf6rhogiBd"
},
"provider": "response-engine"
},
"metric": {
"type": "gauge",
"field": "ses://nps",
"numValue": 3,
"date": "2022-03-07T19:04:11Z"
}
}
]
}
]
}
]
}
Response
200 Successful Bulk Entities Import
{
"entities": [
{
"refId": "new_transaction",
"type": "INSERT"
},
{
"refId": "enrichment1",
"type": "INSERT"
}
]
}
Upsert a contact with a transaction and an enrichment—adding to a batch and list
Request
{
"contacts": [
{
"refId": "new_contact",
"firstName": "Bob",
"lastName": "Smith",
"email": "bob.smith@example.com",
"listMemberships": [
{
"refId": "list1",
"listId": "CG_2X4YDnxnprNKdvi",
"unsubscribed": false
}
],
"transactions": [
{
"refId": "transaction1",
"transactionDate": "2022-07-11T05:33:11Z",
"data": {
"orderNumber": "4343121"
},
"contactListId": "CG_2X4YDnxnprNKdvi",
"platformType": "surveyResponse",
"batches": [
{
"refId": "transaction1-batch1",
"batchId": "BT_ufpqo545ohxslc7"
}
],
"enrichments": [
{
"refId": "transaction1-enrichment1",
"source": {
"context": {
"surveyId": "SV_abFJEwtZF9NyFtH",
"questionId": "QID1",
"responseId": "R_Ggmm1Bf6rhogiBd"
},
"provider": "respone_enginge"
},
"metric": {
"type": "gauge",
"field": "ses://nps",
"enumValue": "enu://10",
"date": "2022-03-07T19:04:11Z"
}
}
]
}
]
}
]
}
Response
200 Successful Bulk Entities Import
{
"entities": [
{
"refId": "upserted_contact",
"type": "UPDATE"
},
{
"refId": "list1",
"type": "INSERT"
},
{
"refId": "transaction1",
"type": "INSERT"
},
{
"refId": "transaction1-batch1",
"type": "INSERT"
},
{
"refId": "transaction1-enrichment1",
"type": "INSERT"
}
]
}
Bulk upsert contacts and add to a list
Request
{
"contacts": [
{
"refId": "new_contact0",
"firstName": "Bob",
"lastName": "Smith",
"email": "bob.smith@example.com",
"listMemberships": [
{
"refId": "new_contact0-list1",
"listId": "CG_2X4YDnxnprNKdvi",
"unsubscribed": false
}
]
},
{
"refId": "new_contact1",
"firstName": "Tim",
"lastName": "Smith",
"email": "tim.smith@example.com",
"listMemberships": [
{
"refId": "new_contact1_list1",
"listId": "CG_2X4YDnxnprNKdvi",
"unsubscribed": false
}
]
},
{
"refId": "new_contact2",
"firstName": "Fred",
"lastName": "Smith",
"email": "fred.smith@example.com",
"listMemberships": [
{
"refId": "new_contact2-list1",
"listId": "CG_2X4YDnxnprNKdvi",
"unsubscribed": false
}
]
},
{
"refId": "new_contact3",
"firstName": "Sue",
"lastName": "Smith",
"email": "sue.smith@example.com",
"listMemberships": [
{
"refId": "new_contact3-list1",
"listId": "CG_2X4YDnxnprNKdvi",
"unsubscribed": false
}
]
}
]
}
Response
200 Successful Bulk Entities Import
{
"entities": [
{
"refId": "new_contact0",
"type": "INSERT"
},
{
"refId": "new_contact0-list1",
"type": "INSERT"
},
{
"refId": "new_contact1",
"type": "INSERT"
},
{
"refId": "new_contact1_list1",
"type": "INSERT"
},
{
"refId": "new_contact2",
"type": "INSERT"
},
{
"refId": "new_contact2-list1",
"type": "INSERT"
},
{
"refId": "new_contact3",
"type": "INSERT"
},
{
"refId": "new_contact3-list1",
"type": "INSERT"
}
]
}
Request Body
{"contacts"=>[{"transactions"=>[{"id"=>{"value"=>"<Error: Too many levels of nesting to fake this schema>"}, "enrichments"=>{"value"=>"<Error: Too many levels of nesting to fake this schema>"}}, {"id"=>{"value"=>"<Error: Too many levels of nesting to fake this schema>"}, "enrichments"=>{"value"=>"<Error: Too many levels of nesting to fake this schema>"}}], "refId"=>"row1", "id"=>"CID_asdflQkGpgvqDbL", "firstName"=>"esse deserunt sint ipsum", "lastName"=>"qui fugiat proident do", "email"=>"do aliquip est sint labori", "phone"=>"111-111-1111", "extRef"=>"laboris commodo", "embeddedData"=>{"pariatur_03"=>"commodo ex voluptate quis", "in_d"=>"amet ut", "ea_26e"=>"magna voluptate deserunt"}, "language"=>"sed", "unsubscribed"=>true, "unsubscribedDate"=>"anim Lorem in", "listMemberships"=>[{"refId"=>"row1-CG_asdflQkGpgvqDbL", "listId"=>"CG_asdflQkGpgvqDbL", "unsubscribed"=>false, "unsubscribedDate"=>"commodo dolore esse ea Excepteur", "embeddedData"=>{"sunta7"=>{"value"=>"<Error: Too many levels of nesting to fake this schema>"}, "ullamco_5_"=>{"value"=>"<Error: Too many levels of nesting to fake this schema>"}, "pariatur0"=>{"value"=>"<Error: Too many levels of nesting to fake this schema>"}}}, {"refId"=>"row1-CG_asdflQkGpgvqDbL", "listId"=>"CG_asdflQkGpgvqDbL", "unsubscribed"=>true, "unsubscribedDate"=>"enim Excepteur", "embeddedData"=>{"Lorem_cd"=>{"value"=>"<Error: Too many levels of nesting to fake this schema>"}, "labore_2"=>{"value"=>"<Error: Too many levels of nesting to fake this schema>"}, "anim__"=>{"value"=>"<Error: Too many levels of nesting to fake this schema>"}, "proident3ad"=>{"value"=>"<Error: Too many levels of nesting to fake this schema>"}}}]}, {"transactions"=>[{"id"=>{"value"=>"<Error: Too many levels of nesting to fake this schema>"}, "enrichments"=>{"value"=>"<Error: Too many levels of nesting to fake this schema>"}}, {"id"=>{"value"=>"<Error: Too many levels of nesting to fake this schema>"}, "enrichments"=>{"value"=>"<Error: Too many levels of nesting to fake this schema>"}}], "refId"=>"row1", "id"=>"CID_asdflQkGpgvqDbL", "firstName"=>"in dolor officia proident incididunt", "lastName"=>"pariatu", "email"=>"aliquip", "phone"=>"111-111-1111", "extRef"=>"dolor consequat sit et", "embeddedData"=>{"irure_9"=>"minim incididunt elit pariatur", "laborumb"=>"magna qui irure in", "cupidatatd1"=>"occaecat non eiusmod"}, "language"=>"proident tempor laboris aliqua", "unsubscribed"=>true, "unsubscribedDate"=>"do Excepteur ea", "listMemberships"=>[{"refId"=>"row1-CG_asdflQkGpgvqDbL", "listId"=>"CG_asdflQkGpgvqDbL", "unsubscribed"=>true, "unsubscribedDate"=>"in eu Exce", "embeddedData"=>{"in_a8"=>{"value"=>"<Error: Too many levels of nesting to fake this schema>"}, "Duisff6"=>{"value"=>"<Error: Too many levels of nesting to fake this schema>"}}}, {"refId"=>"row1-CG_asdflQkGpgvqDbL", "listId"=>"CG_asdflQkGpgvqDbL", "unsubscribed"=>true, "unsubscribedDate"=>"deserunt adipisicing", "embeddedData"=>{"dolor_10"=>{"value"=>"<Error: Too many levels of nesting to fake this schema>"}, "pariatur7"=>{"value"=>"<Error: Too many levels of nesting to fake this schema>"}, "labore_9"=>{"value"=>"<Error: Too many levels of nesting to fake this schema>"}}}]}]}
HEADERS
| Key | Datatype | Required | Description |
|---|---|---|---|
Content-Type | string | ||
Accept | string |
RESPONSES
status: OK
{"entities":[{"refId":"row1-transaction1-BT_asdflQkGpgvqDbL","type":"INSERT","id":"CID_asdflQkGpgvqDbL","version":0,"errors":[{"code":"cupidatat ex","message":"con"},{"code":"dolore esse anim","message":"labore exercitation"}]},{"refId":"row1-transaction1-BT_asdflQkGpgvqDbL","type":"INSERT","id":"CID_asdflQkGpgvqDbL","version":0,"errors":[{"code":"laboris velit","message":"tempor qui"},{"code":"occaecat dolore","message":"et"}]}],"meta":{"httpStatus":"et sint","requestId":"qui sunt nostr","notice":"dolor adipisicing"}}