Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

Import Contacts



Operation overview

operation-overview page anchor

PUT/v3/marketing/contacts/imports

Base url: https://api.sendgrid.com

This endpoint allows a CSV upload containing up to one million contacts or 5GB of data, whichever is smaller. At least one identifier is required for a successful import.

Imports take place asynchronously: the endpoint returns a URL (upload_uri) and HTTP headers (upload_headers) which can subsequently be used to PUT a file of contacts to be imported into our system.

Uploaded CSV files may also be gzip-compressed(link takes you to an external page).

In either case, you must include the field file_type with the value csv in your request body.

The field_mappings parameter is a respective list of field definition IDs to map the uploaded CSV columns to. It allows you to use CSVs where one or more columns are skipped (null) or remapped to the contact field.

For example, if field_mappings is set to [null, "w1", "_rf1"], this means skip column 0, map column 1 to the custom field with the ID w1, and map column 2 to the reserved field with the ID _rf1. See the "Get All Field Definitions" endpoint to fetch your custom and reserved field IDs to use with field_mappings.

Once you receive the response body you can then initiate a second API call where you use the supplied URL and HTTP header to upload your file. For example:

curl --upload-file "file/path.csv" "URL_GIVEN" -H "HEADER_GIVEN"

If you would like to monitor the status of your import job, use the job_id and the "Import Contacts Status" endpoint.

Twilio SendGrid recommends exporting your contacts regularly as a backup to avoid issues or lost data.


Authentication

authentication page anchor
Property nameTypeRequiredDescription
Authorizationstringrequired
Default: Bearer <<YOUR_API_KEY_HERE>>
Schema
Property nameTypeRequiredDescriptionChild properties
list_idsarray[string]Optional

All contacts will be added to each of the specified lists.


file_typeenum<string>required

Upload file type.

Possible values:
csv

field_mappingsarray[string or null]required

Import file header to reserved/custom field mapping.

200400401403404500
Schema
Property nameTypeRequiredDescriptionChild properties
job_idstring

The ID of the import job.


upload_uristring

The URI to PUT the upload file to.


upload_headersarray[object]

A list of headers that must be included in PUT request.

Import Contacts

import-contacts page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
curl

_24
const client = require('@sendgrid/client');
_24
client.setApiKey(process.env.SENDGRID_API_KEY);
_24
_24
const data = {
_24
"file_type": "csv",
_24
"field_mappings": [
_24
"e1_T"
_24
]
_24
};
_24
_24
const request = {
_24
url: `/v3/marketing/contacts/imports`,
_24
method: 'PUT',
_24
body: data
_24
}
_24
_24
client.request(request)
_24
.then(([response, body]) => {
_24
console.log(response.statusCode);
_24
console.log(response.body);
_24
})
_24
.catch(error => {
_24
console.error(error);
_24
});


Rate this page: