Menu

Contacts

Import Contacts

Import Contacts

PUT /marketing/contacts/imports

This endpoint allows a CSV upload containing up to one million contacts or 5GB of data, whichever is smaller.

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 paramter 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 recieve 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'd 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

  • API Key

Headers

Authorization
string
default: Bearer <<YOUR_API_KEY_HERE>>
required

Request Body

object
list_ids
array[string]

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

file_type
string

Upload file type.

Allowed Values: csv
required
field_mappings
array[]

Import file header to reserved/custom field mapping.

minItems: 1
required

Responses

object
job_id
string

The ID of the import job.

upload_uri
string

The URI to PUT the upload file to.

upload_headers
array[object]

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

header
string
value
string
object
errors
array[object]
uniqueItems: True
required
message
string
field
string
error_id
string
parameter
string
object
errors
array[object]
message
string

the error message

field
string or null

the field that generated the error

help
object

helper text or docs for troubleshooting

id
string
{
  "errors": [
    {
      "field": "field_name",
      "message": "error message"
    }
  ]
}
object
errors
array[object]
message
string

the error message

field
string or null

the field that generated the error

help
object

helper text or docs for troubleshooting

id
string
{
  "errors": [
    {
      "field": "field_name",
      "message": "error message"
    }
  ]
}
object

If any of the specified lists do not exist.

errors
array[object]
uniqueItems: True
required
message
string
field
string
error_id
string
parameter
string
object
errors
array[object]
message
string
Rate this page:

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the SendGrid tag on Stack Overflow.

Thank you for your feedback!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

Sending your feedback...
🎉 Thank you for your feedback!
Something went wrong. Please try again.

Thanks for your feedback!

Refer us and get $10 in 3 simple steps!

Step 1

Get link

Get a free personal referral link here

Step 2

Give $10

Your user signs up and upgrade using link

Step 3

Get $10

1,250 free SMSes
OR 1,000 free voice mins
OR 12,000 chats
OR more