openapi: 3.1.0
info:
title: Twilio SendGrid Provisioning Account Contacts API
summary: The Twilio SendGrid Account Provisioning API provides a platform for Twilio SendGrid resellers to manage their customer accounts.
description: 'The Twilio SendGrid Account Provisioning API provides a platform for Twilio SendGrid resellers to manage their customer accounts. This API is for companies that have a formal reseller partnership with Twilio SendGrid.
You can access Twilio SendGrid sub-account functionality without becoming a reseller. If you require sub-account functionality, see the Twilio [SendGrid Subusers](https://docs.sendgrid.com/ui/account-and-settings/subusers) feature, which is available with [Pro and Premier plans](https://sendgrid.com/pricing/).'
termsOfService: https://www.twilio.com/legal/tos
contact:
name: Twilio SendGrid Support
url: https://support.sendgrid.com/hc/en-us
license:
name: MIT
url: https://code.hq.twilio.com/twilio/sendgrid-oas/blob/main/LICENSE
version: 1.0.0
x-sendgrid:
libraryPackage: account_provisioning
servers:
- url: https://api.sendgrid.com
description: for global users and subusers
- url: https://api.eu.sendgrid.com
description: for EU regional subusers
security:
- BearerAuth: []
tags:
- name: Contacts
description: Twilio SendGrid Marketing Campaigns Contacts API
paths:
/v3/marketing/contacts:
put:
operationId: UpdateContact
summary: Add or Update a Contact
tags:
- Contacts
description: '**This endpoint allows the [upsert](https://en.wiktionary.org/wiki/upsert) (insert or update) of up to 30,000 contacts, or 6MB of data, whichever is lower**.
Because the creation and update of contacts is an asynchronous process, the response will not contain immediate feedback on the processing of your upserted contacts. Rather, it will contain an HTTP 202 response indicating the contacts are queued for processing or an HTTP 4XX error containing validation errors. Should you wish to get the resulting contact''s ID or confirm that your contacts have been updated or added, you can use the [Get Contacts by Identifiers operation](https://www.twilio.com/docs/sendgrid/api-reference/contacts/get-contacts-by-identifiers).
Please note that custom fields need to have been already created if you wish to set their values for the contacts being upserted. To do this, please use the [Create Custom Field Definition endpoint](https://www.twilio.com/docs/sendgrid/api-reference/custom-fields/create-custom-field-definition).
You will see a `job_id` in the response to your request. This can be used to check the status of your upsert job. To do so, please use the [Import Contacts Status endpoint](https://www.twilio.com/docs/sendgrid/api-reference/contacts/import-contacts-status).
If the contact already exists in the system, any entries submitted via this endpoint will update the existing contact. In order to update a contact, all of its existing identifiers must be present. Any fields omitted from the request will remain as they were. A contact''s ID cannot be used to update the contact.
The email field will be changed to all lower-case. If a contact is added with an email that exists but contains capital letters, the existing contact with the all lower-case email will be updated.'
requestBody:
content:
application/json:
schema:
type: object
properties:
list_ids:
type: array
description: An array of List ID strings that this contact will be added to.
items:
type: string
format: uuid
contacts:
type: array
description: One or more contacts objects that you intend to upsert. Each contact needs to include at least one of `email`, `phone_number_id`, `external_id`, or `anonymous_id` as an identifier.
minItems: 1
maxItems: 30000
items:
$ref: '#/components/schemas/ContactRequest'
required:
- contacts
responses:
'202':
description: ''
content:
application/json:
schema:
type: object
properties:
job_id:
type: string
description: Indicates that the contacts are queued for processing. Check the job status with the "Import Contacts Status" endpoint.
'400':
description: ''
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/ContactsError'
'401':
$ref: '#/components/responses/MarketingContacts401'
'403':
$ref: '#/components/responses/MarketingContacts403'
'404':
$ref: '#/components/responses/MarketingContacts404'
'500':
$ref: '#/components/responses/MarketingContacts500'
delete:
operationId: DeleteContact
summary: Delete Contacts
tags:
- Contacts
description: "**This endpoint can be used to delete one or more contacts**.\n\nThe query parameter `ids` must set to a comma-separated list of contact IDs for bulk contact deletion.\n\nThe query parameter `delete_all_contacts` must be set to `\"true\"` to delete **all** contacts. \n\nYou must set either `ids` or `delete_all_contacts`.\n\nDeletion jobs are processed asynchronously.\n\nTwilio SendGrid recommends exporting your contacts regularly as a backup to avoid issues or lost data."
parameters:
- name: delete_all_contacts
in: query
description: Must be set to `"true"` to delete all contacts.
required: false
schema:
type: string
- name: ids
in: query
description: A comma-separated list of contact IDs.
required: false
schema:
type: string
responses:
'202':
description: ''
content:
application/json:
schema:
type: object
description: The deletion job has been accepted and is being processed.
properties:
job_id:
type: object
description: The deletion job ID.
required:
- job_id
'400':
description: ''
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
type: object
required:
- errors
'401':
$ref: '#/components/responses/MarketingContacts401'
'403':
$ref: '#/components/responses/MarketingContacts403'
'404':
$ref: '#/components/responses/MarketingContacts404'
'500':
$ref: '#/components/responses/MarketingContacts500'
get:
operationId: ListContact
summary: Get Sample Contacts
tags:
- Contacts
description: "**This endpoint will return up to 50 of the most recent contacts uploaded or attached to a list**. \n\nThis list will then be sorted by email address.\n\nThe full contact count is also returned.\n\nPlease note that pagination of the contacts has been deprecated.\n\nTwilio SendGrid recommends exporting your contacts regularly as a backup to avoid issues or lost data."
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
result:
type: array
items:
$ref: '#/components/schemas/ContactDetails3'
_metadata:
$ref: '#/components/schemas/SelfMetadata'
contact_count:
type: integer
'400':
description: ''
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/ContactsError'
'401':
$ref: '#/components/responses/MarketingContacts401'
'403':
$ref: '#/components/responses/MarketingContacts403'
'404':
description: ''
content:
application/json:
schema:
type: object
'500':
$ref: '#/components/responses/MarketingContacts500'
/v3/marketing/contacts/{id}:
parameters:
- name: id
in: path
required: true
schema:
type: string
get:
operationId: GetContact
summary: Get a Contact by ID
tags:
- Contacts
description: '**This endpoint returns the full details and all fields for the specified contact**.
The "Get Contacts by Identifier" endpoint can be used to get the ID of a contact.'
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ContactDetails3'
'401':
$ref: '#/components/responses/MarketingContacts401'
'403':
$ref: '#/components/responses/MarketingContacts403'
'404':
description: ''
'500':
$ref: '#/components/responses/MarketingContacts500'
/v3/marketing/contacts/batch:
post:
operationId: ListBatchedContact
summary: Get Batched Contacts by IDs
tags:
- Contacts
description: '**This endpoint is used to retrieve a set of contacts identified by their IDs.**
This can be more efficient endpoint to get contacts than making a series of individual `GET` requests to the "Get a Contact by ID" endpoint.
You can supply up to 100 IDs. Pass them into the `ids` field in your request body as an array or one or more strings.
Twilio SendGrid recommends exporting your contacts regularly as a backup to avoid issues or lost data.'
requestBody:
content:
application/json:
schema:
type: object
description: Array of IDs
properties:
ids:
maxItems: 100
type: array
items:
type: string
required:
- ids
example:
ids:
- '1234'
- '1235'
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
result:
type: array
items:
$ref: '#/components/schemas/ContactDetails3'
'401':
$ref: '#/components/responses/MarketingContacts401'
'403':
$ref: '#/components/responses/MarketingContacts403'
'404':
description: ''
content:
application/json:
schema:
type: object
'500':
$ref: '#/components/responses/MarketingContacts500'
/v3/marketing/contacts/{contact_id}/identifiers:
delete:
operationId: DeleteContactIdentifier
summary: Delete a Contact Identifier
tags:
- Contacts
description: '**This endpoint can be used to delete one identifier from a contact.**
Deletion jobs are processed asynchronously.
Note this is different from deleting a contact. If the contact has only one identifier, the asynchronous request will fail. All contacts are required to have at least one identifier.
The request body field `identifier_type` must have a valid value of "EMAIL", "PHONENUMBERID", "EXTERNALID", or "ANONYMOUSID".
'
parameters:
- name: contact_id
in: path
description: Must be set to the `contact_id` of the contact you want to remove the identifier from.
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
identifier_type:
type: string
description: The type of identifier you are removing from the contact.
$ref: '#/components/schemas/IdentifierType'
identifier_value:
type: string
description: The value of the identifier you want to remove from the contact.
required:
- identifier_type
- identifier_value
example:
identifier_type: PHONENUMBERID
identifier_value: '15555555555'
responses:
'202':
description: ''
content:
application/json:
schema:
type: object
description: Indicates that the deletion is queued for processing. Check the job status with the Import Contacts Status endpoint.
properties:
job_id:
type: object
description: The deletion job ID.
required:
- job_id
'400':
description: ''
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
type: object
required:
- errors
'401':
$ref: '#/components/responses/MarketingContacts401'
'403':
$ref: '#/components/responses/MarketingContacts403'
'404':
$ref: '#/components/responses/MarketingContacts404'
'500':
$ref: '#/components/responses/MarketingContacts500'
/v3/marketing/contacts/count:
get:
operationId: ListContactCount
summary: Get Total Contact Count
tags:
- Contacts
description: '**This endpoint returns the total number of contacts you have stored.**
Twilio SendGrid recommends exporting your contacts regularly as a backup to avoid issues or lost data.'
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
contact_count:
type: integer
description: The total number of contacts.
billable_count:
type: integer
default: 0
description: The count of contacts this month for billing purposes.
minimum: 0
billable_breakdown:
type: object
description: '`billable_breakdown` will only appear to the parent user in an account with subusers.'
properties:
total:
type: integer
description: The sum of all the subuser's billable contacts
breakdown:
type: object
description: A map of each subuser's billable contact usage. Each key is the subuser's ID and each value is the usage thus far this month.
minProperties: 0
required:
- contact_count
'401':
$ref: '#/components/responses/MarketingContacts401'
'403':
$ref: '#/components/responses/MarketingContacts403'
'404':
$ref: '#/components/responses/MarketingContacts404'
'500':
$ref: '#/components/responses/MarketingContacts500'
/v3/marketing/contacts/exports:
post:
operationId: ExportContact
summary: Export Contacts
tags:
- Contacts
description: '**Use this endpoint to export lists or segments of contacts**.
If you would just like to have a link to the exported list sent to your email set the `notifications.email` option to `true` in the `POST` payload.
If you would like to download the list, take the `id` that is returned and use the "Export Contacts Status" endpoint to get the `urls`. Once you have the list of URLs, make a `GET` request to each URL provided to download your CSV file(s).
You specify the segments and or/contact lists you wish to export by providing the relevant IDs in, respectively, the `segment_ids` and `list_ids` fields in the request body.
The lists will be provided in either JSON or CSV files. To specify which of these you would required, set the request body `file_type` field to `json` or `csv`.
You can also specify a maximum file size (in MB). If the export file is larger than this, it will be split into multiple files.'
requestBody:
content:
application/json:
schema:
type: object
properties:
list_ids:
description: IDs of the contact lists you want to export.
type: array
items:
type: string
format: uuid
segment_ids:
description: IDs of the contact segments you want to export.
type: array
items:
type: string
notifications:
type: object
properties:
email:
type: boolean
file_type:
type: string
description: File type for export file. Choose from `json` or `csv`.
default: csv
$ref: '#/components/schemas/FileType'
max_file_size:
description: The maximum size of an export file in MB. Note that when this option is specified, multiple output files may be returned from the export.
default: 5000
type: integer
responses:
'202':
description: ''
content:
application/json:
schema:
type: object
properties:
_metadata:
$ref: '#/components/schemas/Metadata'
id:
type: string
description: The ID of the export job.
required:
- _metadata
'400':
description: ''
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/ContactsError'
'401':
$ref: '#/components/responses/MarketingContacts401'
'403':
$ref: '#/components/responses/MarketingContacts403'
'404':
$ref: '#/components/responses/MarketingContacts404'
'500':
$ref: '#/components/responses/MarketingContacts500'
get:
operationId: ListExportContact
summary: Get All Existing Exports
tags:
- Contacts
description: "**Use this endpoint to retrieve details of all current exported jobs**.\n\nIt will return an array of objects, each of which records an export job in flight or recently completed. \n\nEach object's `export_type` field will tell you which kind of export it is and its `status` field will indicate what stage of processing it has reached. Exports which are `ready` will be accompanied by a `urls` field which lists the URLs of the export's downloadable files — there will be more than one if you specified a maximum file size in your initial export request.\n\nUse this endpoint if you have exports in flight but do not know their IDs, which are required for the \"Export Contacts Status\" endpoint."
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
result:
type: array
items:
type: object
properties:
id:
type: string
description: Export jobs ID.
status:
type: string
description: 'Allowed values: `pending`, `ready`, or `failure`.'
created_at:
type: string
description: This ISO8601 timestamp when the export was created.
completed_at:
type: string
description: This ISO8601 timestamp when the export was completed.
expires_at:
type: string
description: This ISO8601 timestamp when the export expires.
urls:
type: array
description: One or more download URLs for the contact file(s) if the status is `ready`.
items:
type: string
user_id:
type: string
description: User ID.
export_type:
type: string
description: 'Allowed types: `contacts_export`, `list_export`, or `segment_export`.'
segments:
type: array
items:
type: object
properties:
ID:
type: string
Name:
type: string
lists:
type: array
items:
type: object
properties:
ID:
type: string
Name:
type: string
_metadata:
type: object
properties:
prev:
type: string
self:
type: string
next:
type: string
_metadata:
type: object
properties:
prev:
type: string
self:
type: string
description: Link to this page.
next:
type: string
description: Link to next page.
'400':
description: ''
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
type: object
properties:
message:
type: string
error_id:
type: string
required:
- message
'401':
$ref: '#/components/responses/MarketingContacts401'
'403':
$ref: '#/components/responses/MarketingContacts403'
'404':
$ref: '#/components/responses/MarketingContacts404'
'500':
$ref: '#/components/responses/MarketingContacts500'
/v3/marketing/contacts/exports/{id}:
parameters:
- name: id
in: path
required: true
schema:
type: string
get:
operationId: GetExportContact
summary: Export Contacts Status
tags:
- Contacts
description: "**This endpoint can be used to check the status of a contact export job**. \n\nTo use this call, you will need the `id` from the \"Export Contacts\" call.\n\nIf you would like to download a list, take the `id` that is returned from the \"Export Contacts\" endpoint and make an API request here to get the `urls`. Once you have the list of URLs, make a `GET` request on each URL to download your CSV file(s).\n\nTwilio SendGrid recommends exporting your contacts regularly as a backup to avoid issues or lost data."
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ContactExport'
'400':
description: ''
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/ContactsError'
'401':
$ref: '#/components/responses/MarketingContacts401'
'403':
$ref: '#/components/responses/MarketingContacts403'
'404':
$ref: '#/components/responses/MarketingContacts404'
'500':
$ref: '#/components/responses/MarketingContacts500'
/v3/marketing/contacts/imports:
put:
operationId: ImportContact
summary: Import Contacts
tags:
- Contacts
description: '**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](https://en.wikipedia.org/wiki/Gzip).
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.
'
requestBody:
content:
application/json:
schema:
type: object
properties:
list_ids:
type: array
description: All contacts will be added to each of the specified lists.
items:
type: string
file_type:
type: string
description: Upload file type.
$ref: '#/components/schemas/FileType1'
field_mappings:
type: array
description: Import file header to reserved/custom field mapping.
uniqueItems: false
minItems: 1
items:
type: string
nullable: true
required:
- file_type
- field_mappings
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
job_id:
type: string
description: The ID of the import job.
upload_uri:
type: string
description: The URI to PUT the upload file to.
upload_headers:
type: array
description: A list of headers that must be included in PUT request.
items:
type: object
properties:
header:
type: string
value:
type: string
required:
- header
- value
'400':
description: ''
content:
application/json:
schema:
type: object
properties:
errors:
type: array
uniqueItems: true
items:
$ref: '#/components/schemas/ContactsError'
required:
- errors
'401':
$ref: '#/components/responses/MarketingContacts401'
'403':
$ref: '#/components/responses/MarketingContacts403'
'404':
description: ''
content:
application/json:
schema:
type: object
description: If any of the specified lists do not exist.
properties:
errors:
type: array
uniqueItems: true
items:
$ref: '#/components/schemas/ContactsError'
required:
- errors
'500':
$ref: '#/components/responses/MarketingContacts500'
/v3/marketing/contacts/imports/{id}:
parameters:
- name: id
in: path
required: true
schema:
type: string
get:
operationId: GetImportContact
summary: Import Contacts Status
tags:
- Contacts
description: "**This endpoint can be used to check the status of a contact import job**. \n\nUse the `job_id` from the \"Import Contacts,\" \"Add or Update a Contact,\" or \"Delete Contacts\" endpoints as the `id` in the path parameter.\n\nIf there is an error with your `PUT` request, download the `errors_url` file and open it to view more details.\n\nThe job `status` field indicates whether the job is `pending`, `completed`, `errored`, or `failed`. \n\nPending means not started. Completed means finished without any errors. Errored means finished with some errors. Failed means finished with all errors, or the job was entirely unprocessable: for example, if you attempt to import file format we do not support.\n\nThe `results` object will have fields depending on the job type.\n\nTwilio SendGrid recommends exporting your contacts regularly as a backup to avoid issues or lost data."
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ContactImport'
'400':
description: ''
content:
application/json:
schema:
type: object
properties:
errors:
$ref: '#/components/schemas/ContactsError'
'401':
$ref: '#/components/responses/MarketingContacts401'
'403':
$ref: '#/components/responses/MarketingContacts403'
'404':
$ref: '#/components/responses/MarketingContacts404'
'500':
$ref: '#/components/responses/MarketingConta
# --- truncated at 32 KB (60 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/sendgrid/refs/heads/main/openapi/sendgrid-contacts-api-openapi.yml