Skip to contentSkip to navigationSkip to topbar
Twilio SendGrid Docs
Page tools
On this page
Looking for more inspiration?Visit the

Import Contacts

Operation overview

operation-overview page anchor

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(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.

Operation details

operation-details page anchor

Authentication

authentication page anchor

Headers

headers page anchor
Property nameTypeRequiredDescription
Authorizationstring
required
Default: Bearer <<YOUR_API_KEY_HERE>>

Request body

request-body page anchor
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.

Min items: 1

Responses

responses page anchor
200400401403404500
Schema
Property nameTypeRequiredDescriptionChild properties
job_idstring

Optional

The ID of the import job.

upload_uristring

Optional

The URI to PUT the upload file to.

upload_headersarray[object]

Optional

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

Import ContactsLink to code sample: Import Contacts
1
const client = require("@sendgrid/client");

2
client.setApiKey(process.env.SENDGRID_API_KEY);

3


4
const data = {

5
  file_type: "csv",

6
  field_mappings: ["e1_T"],

7
};

8


9
const request = {

10
  url: `/v3/marketing/contacts/imports`,

11
  method: "PUT",

12
  body: data,

13
};

14


15
client

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
  });