Contacts
Import Contacts
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.
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
Request Body
All contacts will be added to each of the specified lists.
Upload file type.
Allowed Values: csvImport file header to reserved/custom field mapping.
minItems: 1Responses
The ID of the import job.
The URI to PUT the upload file to.
A list of headers that must be included in PUT request.
the error message
the field that generated the error
helper text or docs for troubleshooting
{
"errors": [
{
"field": "field_name",
"message": "error message"
}
]
}
the error message
the field that generated the error
helper text or docs for troubleshooting
{
"errors": [
{
"field": "field_name",
"message": "error message"
}
]
}
If any of the specified lists do not exist.
Need some help?
We all do sometimes. Get help now from the Twilio SendGrid Support Team.
Running into a coding hurdle? Lean on the wisdom of the crowd by browsing the SendGrid tag on Stack Overflow or visiting Twilio's Stack Overflow Collective.