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.
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