openapi: 3.1.0 security: - BearerAuth: [] info: title: Twilio SendGrid Marketing Campaigns Custom Fields API summary: The Twilio SendGrid Marketing Campaigns Custom Fields API allows you to add extra information about your marketing contacts that is relevant to your needs. description: 'The Twilio SendGrid Marketing Campaigns Custom Fields API allows you to add extra information about your marketing contacts that is relevant to your needs. For example, a fashion retailer might create a custom field for customers'' shoe sizes, an ice cream shop might store customers'' favorite flavors in a custom field, and you can create custom fields that make sense for your business. With custom fields, you can also create [segments](https://docs.sendgrid.com/api-reference/segmenting-contacts-v2/) based on custom fields values. Your custom fields are completely customizable to the use-cases and user information that you need. You can also manage your Custom Fields using the SendGrid application user interface. See [**Using Custom Fields**](https://docs.sendgrid.com/ui/managing-contacts/custom-fields) for more information, including a list of Reserved Fields. You can also manage your custom fields in the [Marketing Campaigns application user interface](https://mc.sendgrid.com/custom-fields).' 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_custom_fields servers: - url: https://api.sendgrid.com description: The Twilio SendGrid v3 API paths: /v3/marketing/field_definitions: post: operationId: CreateFieldDefinition summary: Create Custom Field Definition tags: - Custom Fields description: '**This endpoint creates a new custom field definition.** Custom field definitions are created with the given `name` and `field_type`. Although field names are stored in a case-sensitive manner, all field names must be case-insensitively unique. This means you may create a field named `CamelCase` or `camelcase`, but not both. Additionally, a Custom Field name cannot collide with any Reserved Field names. You should save the returned `id` value in order to update or delete the field at a later date. You can have up to 500 custom fields. The custom field name should be created using only alphanumeric characters (A-Z and 0-9) and underscores (\_). Custom fields can only begin with letters A-Z or underscores (_). The field type can be date, text, or number fields. The field type is important for creating segments from your contact database. **Note: Creating a custom field that begins with a number will cause issues with sending in Marketing Campaigns.**' requestBody: content: application/json: schema: type: object properties: name: type: string minLength: 1 maxLength: 100 field_type: type: string $ref: '#/components/schemas/FieldType' required: - name - field_type example: name: custom_field_name field_type: Text responses: '200': description: '' content: application/json: schema: type: object properties: id: type: string name: type: string minLength: 1 maxLength: 100 field_type: type: string $ref: '#/components/schemas/FieldType2' _metadata: $ref: '#/components/schemas/Metadata' required: - field_type - id - name examples: response: value: id: a1_T name: custom_field_name field_type: Text _metadata: self: https://api.sendgrid.com/v3/marketing/field_definitions/a1_B '400': description: '' content: application/json: schema: type: object properties: errors: type: array uniqueItems: true items: $ref: '#/components/schemas/CustomFieldsError' required: - errors get: operationId: ListFieldDefinition summary: Get All Field Definitions tags: - Custom Fields description: '**This endpoint retrieves all defined Custom Fields and Reserved Fields.**' responses: '200': description: '' content: application/json: schema: type: object minProperties: 0 maxProperties: 500 properties: custom_fields: type: array items: $ref: '#/components/schemas/CustomFieldDefinitionsResponse' reserved_fields: $ref: '#/components/schemas/ReservedFieldDefinitionsResponse' _metadata: $ref: '#/components/schemas/Metadata' required: - custom_fields - reserved_fields examples: response: value: custom_fields: - id: w1 name: num_orders field_type: Number - id: w2 name: dob field_type: Date reserved_fields: - id: _rf0_T name: first_name field_type: Text - id: _rf1_T name: last_name field_type: Text - id: _rf2_T name: email field_type: Text - id: _rf3_T name: alternate_emails field_type: Text - id: _rf4_T name: address_line_1 field_type: Text - id: _rf5_T name: address_line_2 field_type: Text - id: _rf6_T name: city field_type: Text - id: _rf7_T name: state_province_region field_type: Text - id: _rf8_T name: postal_code field_type: Text - id: _rf9_T name: country field_type: Text - id: _rf10_T name: phone_number field_type: Text - id: _rf11_T name: whatsapp field_type: Text - id: _rf12_T name: line field_type: Text - id: _rf13_T name: facebook field_type: Text - id: _rf14_T name: unique_name field_type: Text - id: _rf15_T name: email_domains field_type: Text read_only: true - id: _rf16_D name: last_clicked field_type: Date read_only: true - id: _rf17_D name: last_opened field_type: Date read_only: true - id: _rf18_D name: last_emailed field_type: Date read_only: true - id: _rf19_T name: singlesend_id field_type: Text read_only: true - id: _rf20_T name: automation_id field_type: Text read_only: true - id: _rf21_D name: created_at field_type: Date read_only: true - id: _rf22_D name: updated_at field_type: Date read_only: true - id: _rf23_T name: contact_id field_type: Text read_only: true _metadata: self: https://example.com/marketing/field_definitions /v3/marketing/field_definitions/{custom_field_id}: parameters: - name: custom_field_id in: path required: true schema: type: string patch: operationId: UpdateFieldDefinition summary: Update Custom Field Definition tags: - Custom Fields description: '**This endpoint allows you to update a defined Custom Field.** Only your Custom fields can be modified; Reserved Fields cannot be updated.' requestBody: content: application/json: schema: type: object properties: name: type: string minLength: 1 maxLength: 100 required: - name example: name: new_custom_field_name responses: '200': description: '' content: application/json: schema: type: object properties: id: type: string name: type: string minLength: 1 maxLength: 100 field_type: type: string $ref: '#/components/schemas/FieldType2' _metadata: $ref: '#/components/schemas/Metadata' required: - field_type - id - name examples: response: value: id: a1_T name: custom_field_name field_type: Text _metadata: self: https://api.sendgrid.com/v3/marketing/field_definitions/a1_B '400': description: '' content: application/json: schema: type: object properties: errors: type: array uniqueItems: true items: $ref: '#/components/schemas/CustomFieldsError' required: - errors '404': description: '' content: application/json: schema: type: object properties: errors: type: array uniqueItems: true items: $ref: '#/components/schemas/CustomFieldsError' required: - errors delete: operationId: DeleteFieldDefinition summary: Delete Custom Field Definition tags: - Custom Fields description: '**This endpoint deletes a defined Custom Field.** You can delete only Custom Fields; Reserved Fields cannot be deleted.' responses: '204': description: '' '404': description: '' content: application/json: schema: type: object required: - errors properties: errors: type: array uniqueItems: true items: $ref: '#/components/schemas/CustomFieldsError' components: schemas: ReservedFieldDefinitionsResponse: title: reserved_field_definitions_response type: array items: type: object properties: name: type: string minLength: 1 maxLength: 100 field_type: type: string $ref: '#/components/schemas/FieldType1' read_only: type: boolean default: false description: When `true` this means API consumers are unable to set the value of this field on contacts. required: - name - field_type example: - id: _rf20_T name: automation_id field_type: Text read_only: true CustomFieldsError: title: error type: object properties: message: type: string field: type: string error_id: type: string parameter: type: string required: - message Metadata: title: _metadata type: object properties: prev: type: string format: uri self: type: string format: uri next: type: string format: uri count: type: integer minimum: 0 CustomFieldDefinitionsResponse: title: custom_field_definitions_response type: object properties: id: type: string name: type: string minLength: 1 maxLength: 100 field_type: type: string $ref: '#/components/schemas/FieldType2' required: - id - name - field_type example: id: a1_D name: custom_field_name field_type: Date FieldType: type: string enum: - Text - Number - Date FieldType1: type: string enum: - Text - Number - Date FieldType2: type: string enum: - Text - Number - Date responses: {} 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: Custom Fields description: Twilio SendGrid Marketing Campaigns Custom Fields API externalDocs: description: Twilio SendGrid's official developer documentation. url: https://www.twilio.com/docs/sendgrid