Create Bulk Entity Import
POST/directories/:directoryId/imports
Create a Bulk Entity Import.
JSON Body Size Limit
The size of the JSON body accepted by this API call is 5 MB with a maximum of 1,000 refIds per import.
The API returns an error if the size of the body or contact count exceeds these limits.
For example, you can import 1,000 contacts. Or you can import 500 contacts with 500 transactions. Or 333 contacts with 333 transactions and 333 list memberships.
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
Responses
- 200
- 400
- 401
- default
Successful Bulk Entities Import
Bad Request
Unauthorized
A default error response