SendGrid Custom Fields API

openapi: 3.2.0
info:
  title: Sendgrid Custom Fields API
  version: 1.0.0
  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
  termsOfService: https://www.twilio.com/legal/tos
  x-refined-note:
  - x-sendgrid differs across the merged source definitions and was not carried
  description: 'Operations tagged Custom Fields across 2 of this provider''s published API definitions: tsg_lmc_contactdb_v3.yaml, tsg_mc_custom_fields_v3.yaml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.sendgrid.com
  description: The Twilio SendGrid v3 API
security:
- BearerAuth: []
tags:
- name: Custom Fields
  description: 'Twilio SendGrid Legacy Marketing Campaigns Contacts: Custom Fields API'
paths:
  /v3/contactdb/custom_fields:
    post:
      operationId: CreateCustomField
      summary: Create a Custom Field
      tags:
      - Custom Fields
      description: '**This endpoint allows you to create a custom field.**


        **You can create up to 120 custom fields.**'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                type:
                  type: string
              example:
                name: pet
                type: text
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactdbCustomFieldId2xx'
              examples:
                response:
                  value:
                    id: 1
                    name: pet
                    type: text
        '400':
          description: The request was formatted incorrectly or missing required parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    errors:
                    - field: null
                      message: Returned if request body is invalid JSON
                    - field: type
                      message: Returned if custom field type is invalid or not provided
                    - field: name
                      message: Returned if custom field name is not provided
    get:
      operationId: ListCustomField
      summary: Retrieve all custom fields
      tags:
      - Custom Fields
      description: '**This endpoint allows you to retrieve all custom fields.**'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                title: List All Custom Fields response
                type: object
                properties:
                  custom_fields:
                    type: array
                    items:
                      $ref: '#/components/schemas/ContactdbCustomFieldId2xx'
                required:
                - custom_fields
              examples:
                response:
                  value:
                    custom_fields:
                    - id: 6234
                      name: age
                      type: number
                    - id: 6233
                      name: country
                      type: text
                    - id: 6235
                      name: favorite_color
                      type: text
                    - id: 6239
                      name: fname
                      type: text
                    - id: 6240
                      name: lname
                      type: text
                    - id: 49439
                      name: pet
                      type: text
        '401':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    errors:
                    - field: null
                      message: authorization required
    servers:
    - url: https://api.sendgrid.com
      description: The Twilio SendGrid v3 API
  /v3/contactdb/custom_fields/{custom_field_id}:
    parameters:
    - name: custom_field_id
      in: path
      description: The ID of the custom field that you want to retrieve.
      required: true
      schema:
        type: integer
    get:
      operationId: GetCustomField
      summary: Retrieve a Custom Field
      tags:
      - Custom Fields
      description: '**This endpoint allows you to retrieve a custom field by ID.**'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactdbCustomFieldId2xx'
              examples:
                response:
                  value:
                    id: 1
                    name: pet
                    type: text
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    errors:
                    - message: invalid id
        '401':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    errors:
                    - field: null
                      message: authorization required
        '404':
          description: The `custom_field_id` does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    errors:
                    - message: Custom field ID does not exist
    delete:
      operationId: DeleteCustomField
      summary: Delete a Custom Field
      tags:
      - Custom Fields
      description: '**This endpoint allows you to delete a custom field by ID.**'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      responses:
        '202':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    message: Custom Field delete is processing.
        '400':
          description: The `custom_field_id` is not valid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    errors:
                    - message: Custom field in use by one or more segment conditions
                    - message: Custom field ID does not exist
        '401':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    errors:
                    - field: null
                      message: authorization required
        '404':
          description: The `custom_field_id` does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    errors:
                    - message: Custom field ID does not exist
    servers:
    - url: https://api.sendgrid.com
      description: The Twilio SendGrid v3 API
  /v3/contactdb/reserved_fields:
    get:
      operationId: ListReservedField
      summary: Retrieve reserved fields
      tags:
      - Custom Fields
      description: '**This endpoint allows you to list all fields that are reserved and can''t be used for custom field names.**'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  reserved_fields:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                        type:
                          type: string
              examples:
                response:
                  value:
                    reserved_fields:
                    - name: first_name
                      type: text
                    - name: last_name
                      type: text
                    - name: email
                      type: text
                    - name: created_at
                      type: date
                    - name: updated_at
                      type: date
                    - name: last_emailed
                      type: date
                    - name: last_clicked
                      type: date
                    - name: last_opened
                      type: date
                    - name: lists
                      type: set
                    - name: campaigns
                      type: set
                    - name: my_custom_field
                      type: text
        '401':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    errors:
                    - field: null
                      message: authorization required
    servers:
    - url: https://api.sendgrid.com
      description: The Twilio SendGrid v3 API
  /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
    servers:
    - url: https://api.sendgrid.com
      description: The Twilio SendGrid v3 API
  /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'
    servers:
    - url: https://api.sendgrid.com
      description: The Twilio SendGrid v3 API
components:
  schemas:
    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
    Type:
      type: string
      enum:
      - date
      - text
      - number
    ContactdbCustomFieldId2xx:
      title: ContactDB Custom field schema with ID.
      type: object
      properties:
        name:
          type: string
          description: The name of the field
        type:
          type: string
          description: The type of the field.
          $ref: '#/components/schemas/Type'
        id:
          type: number
          description: The ID of the custom field.
    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
    CustomFieldsError:
      title: error
      type: object
      properties:
        message:
          type: string
        field:
          type: string
        error_id:
          type: string
        parameter:
          type: string
      required:
      - message
    FieldType1:
      type: string
      enum:
      - Text
      - Number
      - Date
    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
    FieldType2:
      type: string
      enum:
      - Text
      - Number
      - Date
    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
  parameters:
    OnBehalfOf:
      name: on-behalf-of
      in: header
      description: 'The `on-behalf-of` header allows you to make API calls from a parent account on behalf of the parent''s Subusers or customer accounts. You will use the parent account''s API key when using this header. When making a call on behalf of a customer account, the property value should be "account-id" followed by the customer account''s ID (e.g., `on-behalf-of: account-id <account-id>`). When making a call on behalf of a Subuser, the property value should be the Subuser''s username (e.g., `on-behalf-of: <subuser-username>`). See [**On Behalf Of**](https://docs.sendgrid.com/api-reference/how-to-use-the-sendgrid-v3-api/on-behalf-of) for more information.'
      required: false
      schema:
        type: string
  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.
externalDocs:
  description: Twilio SendGrid's official developer documentation.
  url: https://www.twilio.com/docs/sendgrid
x-refined-from:
- tsg_lmc_contactdb_v3.yaml
- tsg_mc_custom_fields_v3.yaml