openapi: 3.1.0 security: - BearerAuth: [] info: title: Twilio SendGrid Marketing Campaigns Contacts API summary: The Twilio SendGrid Marketing Campaigns Contacts API allows you to manage all of your marketing contacts programmatically. description: 'The Twilio SendGrid Marketing Campaigns Contacts API allows you to manage all of your marketing contacts programmatically. You can also import and export contacts using this API. The Contacts API allows you to associate contacts with lists and segments; however, to manage the lists and segments themselves, see the [Lists API](https://docs.sendgrid.com/api-reference/lists/) and [Segments API](https://docs.sendgrid.com/api-reference/segmenting-contacts-v2/). You can also manage your marketing contacts with the [Marketing Campaigns application user interface](https://mc.sendgrid.com/contacts). See [**How to Send Email with New Marketing Campaigns**](https://docs.sendgrid.com/ui/sending-email/how-to-send-email-with-marketing-campaigns) for more information.' 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: mc_contacts servers: - url: https://api.sendgrid.com description: The Twilio SendGrid v3 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 \u2014 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\n\ Pending 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/MarketingContacts500' /v3/marketing/contacts/search: post: operationId: SearchContact summary: Search Contacts tags: - Contacts description: '**Use this endpoint to locate contacts**. The request body''s `query` field accepts valid [SGQL](https://sendgrid.com/docs/for-developers/sending-email/segmentation-query-language/) for searching for a contact. Because contact emails are stored in lower case, using SGQL to search by email address requires the provided email address to be in lower case. The SGQL `lower()` function can be used for this. Only the first 50 contacts that meet the search criteria will be returned. If the query takes longer than 20 seconds, a `408 Request Timeout` status will be returned. Formatting the `created_at` and `updated_at` values as Unix timestamps is deprecated. Instead, they are returned as ISO format as string.' requestBody: content: application/json: schema: type: object properties: query: type: string description: An SGQL search string or other pattern. required: - query example: query: email LIKE 'ENTER_COMPLETE_OR_PARTIAL_EMAIL_ADDRESS_HERE%' AND CONTAINS(list_ids, 'YOUR_LIST_IDs') 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: number description: The total number of contacts matched. required: - contact_count '400': description: '' content: application/json: schema: type: object properties: errors: type: array items: type: object properties: field: type: string message: type: string '401': $ref: '#/components/responses/MarketingContacts401' '403': $ref: '#/components/responses/MarketingContacts403' '404': $ref: '#/components/responses/MarketingContacts404' '408': description: '' '500': description: '' content: application/json: schema: type: object properties: errors: type: array items: type: object properties: message: type: string /v3/marketing/contacts/search/emails: post: operationId: ListContactByEmail summary: Get Contacts by Emails tags: - Contacts description: "**This endpoint allows you to retrieve up to 100 contacts matching\ \ the searched `email` address(es), including any `alternate_emails`.** \n\ \nEmail addresses are unique to a contact, meaning this endpoint can treat\ \ an email address as a primary key to search by. The contact object associated\ \ with the address, whether it is their `email` or one of their `alternate_emails`\ \ will be returned if matched.\n\nEmail addresses in the search request do\ \ not need to match the case in which they're stored, but the email addresses\ \ in the result will be all lower case. Empty strings are excluded from the\ \ search and will not be returned.\n\nThis endpoint should be used in place\ \ of the \"Search Contacts\" endpoint when you can provide exact email addresses\ \ and do not need to include other [Segmentation Query Language (SGQL)](https://sendgrid.com/docs/for-developers/sending-email/segmentation-query-language/)\ \ filters when searching.\n\nIf you need to access a large percentage of your\ \ contacts, we recommend exporting your contacts with the \"Export Contacts\"\ \ endpoint and filtering the client side results.\n\nThis endpoint returns\ \ a `200` status code when any contacts match the address(es) you supplied.\ \ When searching multiple addresses in a single request, it is possible that\ \ some addresses will match a contact while others will not. When a partially\ \ successful search like this is made, the matching contacts are returned\ \ in an object and an error message is returned for the email address(es)\ \ that are not found. \n\nThis endpoint returns a `404` status code when no\ \ contacts are found for the provided email address(es).\n\nA `400` status\ \ code is returned if any searched addresses are invalid.\n\nTwilio SendGrid\ \ recommends exporting your contacts regularly as a backup to avoid issues\ \ or lost data." requestBody: content: application/json: schema: type: object description: '' properties: emails: type: array description: One or more primary and/or alternate email addresses to search for in your Marketing Campaigns contacts. items: type: string maxLength: 100 phone_number_id: type: string description: The contact's Phone Number ID. This is required to be a valid phone number. external_id: type: string description: The contact's External ID. maxLength: 254 anonymous_id: type: string description: The contact's Anonymous ID. maxLength: 254 required: - emails example: emails: - jane_doe@example.com - john_doe@example.com - joann_doe@example.com responses: '200': description: '' content: application/json: schema: type: object description: An object containing one or more of the email addresses matching the searched addresses in your contacts. properties: result: type: object patternProperties: ^[A-Za-z0-9\._%\+-]+@[A-Za-z0-9\.-]+\.[A-Za-z]{2,6}$: type: object description: An email address matching a searched address in your contacts that conforms to the above regex string. properties: contact: $ref: '#/components/schemas/ContactDetails3' error: type: string example: result: jane_doe@example.com: contact: address_line_1: '' address_line_2: '' alternate_emails: - janedoe@example1.com city: '' country: '' email: jane_doe@example.com first_name: Jane id: asdf-Jkl-zxCvBNm last_name: Doe list_ids: [] segment_ids: [] postal_code: '' state_province_region: '' phone_number: '' whatsapp: '' line: '' facebook: '' unique_name: '' custom_fields: {} created_at: '2021-03-02T15:25:47Z' updated_at: '2021-03-30T15:26:16Z' _metadata: self: john_doe@example.com: contact: address_line_1: '' address_line_2: '' alternate_emails: [] city: '' country: '' email: john_doe@example.com first_name: Jane id: asdf-Jkl-qWeRTy last_name: Doe list_ids: [] segment_ids: [] postal_code: '' state_province_region: '' phone_number: '' whatsapp: '' line: '' facebook: '' unique_name: '' custom_fields: {} created_at: '2020-01-02T15:25:47Z' updated_at: '2020-12-20T15:26:16Z' _metadata: self: joann_doe@example.com: error: contact not found examples: response: value: result: jane_doe@example.com: contact: address_line_1: '' address_line_2: '' alternate_emails: - janedoe@example1.com city: '' country: '' email: jane_doe@example.com first_name: Jane id: asdf-Jkl-zxCvBNm last_name: Doe list_ids: [] segment_ids: [] postal_code: '' state_province_region: '' phone_number: '' whatsapp: '' line: '' facebook: '' unique_name: '' custom_fields: {} created_at: '2021-03-02T15:25:47Z' updated_at: '2021-03-30T15:26:16Z' _metadata: self: john_doe@example.com: contact: address_line_1: '' address_line_2: '' alternate_emails: [] city: '' country: '' email: john_doe@example.com first_name: Jane id: asdf-Jkl-qWeRTy last_name: Doe list_ids: [] segment_ids: [] postal_code: '' state_province_region: '' phone_number: '' whatsapp: '' line: '' facebook: '' unique_name: '' custom_fields: {} created_at: '2020-01-02T15:25:47Z' updated_at: '2020-12-20T15:26:16Z' _metadata: self: joann_doe@example.com: error: contact not found '400': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': $ref: '#/components/responses/MarketingContacts401' '403': $ref: '#/components/responses/MarketingContacts403' '404': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: '' content: application/json: schema: type: object properties: errors: type: array items: type: object properties: message: type: string /v3/marketing/contacts/search/identifiers/{identifier_type}: parameters: - name: identifier_type in: path required: true description: The type of identifier to search for. You can use only one type of identifier per search. schema: type: string $ref: '#/components/schemas/IdentifierType1' post: operationId: GetContactByIdentifiers summary: Get Contacts by Identifiers tags: - Contacts description: 'Use this endpoint to retrieve up to 100 contacts that match the requested identifier values for a single identifier type. `identifier_type` must be a valid identifier type: `email`, `phone_number_id`, `external_id`, or `anonymous_id`. Use this endpoint instead of the [Search Contacts endpoint](https://www.twilio.com/docs/sendgrid/api-reference/contacts/search-contacts) when you can provide exact identifiers and do not need to include other [Segmentation Query Language (SGQL)](https://www.twilio.com/docs/sendgrid/for-developers/sending-email/segmentation-query-language/) filters when searching. This endpoint returns a `200` status code when any contacts match the identifiers you supplied. When searching multiple identifier values in a single request, it is possible that some will match a contact while others will not. When a partially successful search like this is made, the matching contacts are returned in an object and an error message is returned for the identifier values that are not found. This endpoint returns a `404` status code when no contacts are found for the provided identifiers. This endpoint returns a `400` status code if any searched addresses are invalid. Twilio SendGrid recommends exporting your contacts regularly as a backup to avoid issues or lost data. ' requestBody: content: application/json: schema: type: object description: '' properties: identifiers: type: array description: One or more more identifier values of the given identifier type to search for in your Marketing Campaigns contacts. items: type: string required: - identifiers example: identifiers: - contact@example.com responses: '200': description: '' content: application/json: schema: type: object description: An object containing the contacts that match the searched identifier values. properties: result: type: object additionalProperties: type: object description: An identifiers value matching a searched identifier in your contacts. For example, if you use the email identifier type, the email address will be returned. properties: contact: $ref: '#/components/schemas/ContactDetails3' error: type: string example: result: jane_doe@example.com: contact: address_line_1: '' address_line_2: '' alternate_emails: - janedoe@example1.com city: '' country: '' email: jane_doe@example.com phone_number_id: '+14152279968' external_id: extid_1709597080488434000_1_1 anonymous_id: anonid_1709597080488436000_1_1 first_name: Jane id: asdf-Jkl-zxCvBNm last_name: Doe list_ids: [] segment_ids: [] postal_code: '' state_province_region: '' phone_number: '' whatsapp: '' line: '' facebook: '' unique_name: '' custom_fields: {} created_at: '2021-03-02T15:25:47Z' updated_at: '2021-03-30T15:26:16Z' _metadata: self: '400': description: '' content: application/json: schema: $ref: '#/components/schemas/ContactsError' '401': $ref: '#/components/responses/MarketingContacts401' '403': $ref: '#/components/responses/MarketingContacts403' '404': description: '' content: application/json: schema: $ref: '#/components/schemas/ContactsError' '500': description: '' content: application/json: schema: type: object properties: errors: type: array items: type: object properties: message: type: string components: schemas: ContactImport: title: contact-import type: object properties: id: type: string description: The job ID. status: type: string description: 'The job state. Allowed values: `pending`, `completed`, `errored`, or `failed`.' job_type: type: string description: 'The job type. Allowed values: `upsert`, or `delete`.' results: type: object description: Result map of the import job. properties: requested_count: description: Requested contact count from the import. type: number created_count: description: Created contact count from the import. type: number updated_count: description: Updated contact count from the import. type: number deleted_count: description: Count of deleted contacts that resulted in error. type: number errored_count: description: Count of imported contacts that resulted in error. type: number errors_url: type: string description: The download URL of the file which provides information about any errors. started_at: description: The ISO8601 timestamp when the job was created. type: string finished_at: description: The ISO8601 timestamp when the job was finished. type: string ContactExport: title: contact-export type: object properties: id: type: string status: type: string description: 'The export job''s status. Allowed values: `pending`, `ready`, or `failure`.' $ref: '#/components/schemas/Status' created_at: type: string description: The ISO8601 timestamp when the export was begun. updated_at: type: string description: The ISO8601 timestamp when the export was updated. completed_at: type: string description: The ISO8601 timestamp when the export was completed. expires_at: type: string description: The ISO8601 timestamp when the exported file on S3 will expire. urls: type: array description: One or more download URLs for the contact file if the status is `ready`. items: type: string message: type: string description: A human readable message if the status is `failure`. _metadata: $ref: '#/components/schemas/Metadata' contact_count: type: integer description: The total number of exported contacts. required: - id - status - created_at - updated_at - expires_at ContactDetails3: title: contact-details3 type: object properties: id: type: string first_name: type: string last_name: type: string unique_name: type: string email: type: string phone_number_id: type: string external_id: type: string anonymous_id: type: string alternate_emails: type: array items: type: string address_line_1: type: string address_line_2: type: string city: type: string state_province_region: type: string country: type: string postal_code: type: string phone_number: type: string whatsapp: type: string line: type: string facebook: type: string list_ids: type: array items: type: string segment_ids: type: array items: type: string custom_fields: type: object created_at: type: string updated_at: type: string _metadata: $ref: '#/components/schemas/SelfMetadata' required: - id - list_ids - segment_ids - created_at - updated_at ContactsError: title: error type: object properties: message: type: string field: type: string error_id: type: string parameter: type: string example: field: field_name message: error message required: - message ContactRequest: title: contact-request type: object properties: address_line_1: type: string description: The first line of the address. maxLength: 100 address_line_2: type: string description: An optional second line for the address. maxLength: 100 alternate_emails: type: array description: Additional emails associated with the contact. minItems: 0 maxItems: 5 items: type: string maxLength: 254 city: type: string description: The contact's city. maxLength: 60 country: type: string description: The contact's country. Can be a full name or an abbreviation. maxLength: 50 email: type: string description: The contact's primary email. This is required to be a valid email. maxLength: 254 phone_number_id: type: string description: The contact's Phone Number ID. This must be a valid phone number. external_id: type: string description: The contact's External ID. maxLength: 254 anonymous_id: type: string description: The contact's Anonymous ID. maxLength: 254 first_name: type: string description: The contact's personal name. maxLength: 50 last_name: type: string description: The contact's family name. maxLength: 50 postal_code: type: string description: The contact's ZIP code or other postal code. state_province_region: type: string description: The contact's state, province, or region. maxLength: 50 custom_fields: type: object description: An object of custom field IDs and the values you want to associate with those custom fields. You can retrieve the IDs of your custom fields from the [Get All Field Definitions endpoint](https://docs.sendgrid.com/api-reference/custom-fields/get-all-field-definitions). properties: w1: type: string description: 'The properties in this object are made up of a key (the custom field ID) and value you want associated with that custom field. For example `{"w1": "coffee"}`.' example: w1: coffee w33: '42' e2: blue Metadata: title: metadata type: object properties: prev: type: string format: uri description: The URL of the previous page of results. If this field isn't present, you're at the start of the list. self: type: string format: uri description: The URL of the current page of results. next: type: string format: uri description: The URL of the next page of results. If this field isn't present, you're at the end of the list. count: type: number description: The number of items in the entire list, i.e., across all pages. SelfMetadata: title: selfMetadata type: object properties: self: type: string description: A link to this object. ErrorResponse: type: object properties: errors: type: array items: type: object properties: message: type: string description: An error message. field: description: When applicable, this property value will be the field that generated the error. nullable: true type: string help: type: object description: When applicable, this property value will be helper text or a link to documentation to help you troubleshoot the error. id: type: string description: When applicable, this property value will be an error ID. example: errors: - field: field_name message: error message IdentifierType: type: string enum: - EMAIL - PHONENUMBERID - EXTERNALID - ANONYMOUSID FileType: type: string enum: - csv - json FileType1: type: string enum: - csv IdentifierType1: type: string enum: - email - phone_number_id - external_id - anonymous_id Status: type: string enum: - pending - ready - failure responses: MarketingContacts401: description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' MarketingContacts403: description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' MarketingContacts404: description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' MarketingContacts500: description: '' content: application/json: schema: type: object properties: errors: type: array items: type: object properties: message: type: string parameters: {} examples: {} requestBodies: {} headers: {} securitySchemes: BearerAuth: type: http scheme: bearer description: Twilio SendGrid requires you to authenticate with its APIs using an API key. The API key must be sent as a bearer token in the Authorization header. tags: - name: Contacts description: Twilio SendGrid Marketing Campaigns Contacts API externalDocs: description: Twilio SendGrid's official developer documentation. url: https://www.twilio.com/docs/sendgrid