On this page

Import Contacts

Operation overview

PUT/v3/marketing/contacts/imports

Base url: https://api.sendgrid.com (The Twilio SendGrid v3 API)

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.

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.

Operation details

Authentication

API Key

Headers

Property nameTypeRequiredDescription

Authorizationstringrequired

Default: Bearer <<YOUR_API_KEY_HERE>>

Request body

Encoding type:application/json

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]required

Import file header to reserved/custom field mapping.

Responses

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.

Show child properties for upload_headers

Import Contacts

1const client = require("@sendgrid/client");
2client.setApiKey(process.env.SENDGRID_API_KEY);
3
4const data = {
5  file_type: "csv",
6  field_mappings: ["e1_T"],
7};
8
9const request = {
10  url: `/v3/marketing/contacts/imports`,
11  method: "PUT",
12  body: data,
13};
14
15client
16  .request(request)
17  .then(([response, body]) => {
18    console.log(response.statusCode);
19    console.log(response.body);
20  })
21  .catch((error) => {
22    console.error(error);
23  });