{ "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.\n\nWith 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.\n\nYou 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.**\n\nCustom 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.\n\nThe 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.\n\n**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.**\n\nOnly 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.**\n\nYou 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" } }