> ## Documentation Index
> Fetch the complete documentation index at: https://docs.autosend.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Custom Field

> Create a new custom field to store additional contact attributes using the AutoSend API.

export const APP_PATHS = {
  home: '/',
  quickstart: '/quickstart',
  domainConfiguration: '/domain',
  apiReference: '/api-reference',
  sendEmail: '/api-reference/mails/send',
  bulkSendEmail: '/api-reference/mails/bulk',
  upsertContactApiRef: '/api-reference/contacts/upsert-contact',
  transactional: '/transactional-emails',
  emailActivity: '/transactional-emails/email-activity',
  emailTemplates: '/transactional-emails/email-templates',
  sendingEmail: '/quickstart/email-using-api',
  transactionalTroubleshooting: '/transactional-emails/troubleshooting',
  marketing: '/marketing-emails',
  campaigns: '/marketing-emails/campaigns',
  contacts: '/marketing-emails/contacts',
  contactsIntroduction: '/marketing-emails/contacts/introduction',
  contactsImportCsv: '/marketing-emails/contacts/import-csv',
  contactsLists: '/marketing-emails/contacts/lists',
  contactsSegments: '/marketing-emails/contacts/segments',
  contactsCustomFields: '/marketing-emails/contacts/contact-properties',
  contactsContactProperties: '/marketing-emails/contacts/contact-properties',
  createContactPropertyApiRef: '/api-reference/contact-properties/create',
  listContactPropertiesApiRef: '/api-reference/contact-properties/list',
  getContactPropertyApiRef: '/api-reference/contact-properties/get-by-name',
  deleteContactPropertyApiRef: '/api-reference/contact-properties/delete',
  sender: '/marketing-emails/sender',
  unsubscribeGroups: '/others/unsubscribe-groups',
  webhookIntroduction: '/others/webhooks/introduction',
  webhookEventType: '/others/webhooks/event-type',
  webhookRetries: '/others/webhooks/retries',
  webhookVerifyRequests: '/others/webhooks/verify-requests',
  dynamicTemplates: '/dynamic-templates',
  guides: '/guides',
  sitemap: '/sitemap.xml',
  team: '/others/team',
  automations: '/automations',
  events: '/automations/events',
  sendEventApi: '/api-reference/events/send-event',
  smtpIntroduction: '/quickstart/smtp',
  betterAuth: '/guides/better-auth',
  convexGuide: '/guides/convex',
  templateVariables: '/transactional-emails/variables',
  suppressions: '/others/suppressions',
  rateLimit: '/api-reference/rate-limit',
  nodejsSdk: '/sdk/nodejs',
  smtpIntegrationGuides: '/guides/smtp',
  apiKeys: '/api-keys',
  encryptedPayloads: '/others/encrypted-payloads',
  apiReferenceIntroduction: '/api-reference/introduction',
  lovableGuide: '/ai/integrations/lovable',
  aiIntroduction: '/ai/introduction',
  aiSkills: '/ai/skills',
  aiMcpServer: '/ai/mcp-server',
  aiLovable: '/ai/integrations/lovable',
  aiBolt: '/ai/integrations/bolt',
  aiV0: '/ai/integrations/v0',
  aiReplit: '/ai/integrations/replit',
  mcpClaude: '/ai/mcp-clients/claude',
  mcpCursor: '/ai/mcp-clients/cursor',
  mcpCopilot: '/ai/mcp-clients/copilot',
  mcpWindsurf: '/ai/mcp-clients/windsurf',
  mcpCodex: '/ai/mcp-clients/codex',
  mcpAntigravity: '/ai/mcp-clients/antigravity',
  mcpChatgpt: '/ai/mcp-clients/chatgpt',
  mcpRaycast: '/ai/mcp-clients/raycast',
  domainWarmup: '/marketing-emails/domain-warmup',
  projects: '/projects',
  createAutomationApi: '/api-reference/automations/create-automation',
  migrationSendgrid: '/migration/sendgrid',
  migrationResend: '/migration/resend',
  auth0CustomAction: '/guides/auth0-custom-action',
  accountBilling: '/others/account/billing',
  accountUsage: '/others/account/usage',
  inboundIntroduction: '/inbound/introduction',
  listInboundMessagesApi: '/api-reference/inbound-emails/list-messages',
  getInboundMessageApi: '/api-reference/inbound-emails/get-message',
  downloadInboundAttachmentApi: '/api-reference/inbound-emails/download-attachment',
  replyToInboundMessageApi: '/api-reference/inbound-emails/reply-to-message',
  wikiDailySendingLimit: '/wiki/daily-sending-limit'
};

<Warning>
  **Deprecated.** Custom fields are now called contact properties. This `/custom-fields` endpoint still works as an alias, but new integrations should use <a href={APP_PATHS.createContactPropertyApiRef}>Create Contact Property</a>. The new endpoint accepts `name`/`type`; the legacy `fieldName`/`fieldType` are still accepted.
</Warning>

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.autosend.com/v1/custom-fields \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --data '{
      "fieldName": "company",
      "fieldType": "string"
    }'
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.autosend.com/v1/custom-fields"

  headers = {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
  }

  payload = {
      "fieldName": "company",
      "fieldType": "string"
  }

  response = requests.post(url, json=payload, headers=headers)
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.autosend.com/v1/custom-fields", {
    method: "POST",
    headers: {
      Authorization: "Bearer <token>",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      fieldName: "company",
      fieldType: "string",
    }),
  });

  const data = await response.json();
  console.log(data);
  ```

  ```php PHP theme={null}
  <?php
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://api.autosend.com/v1/custom-fields",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode([
      "fieldName" => "company",
      "fieldType" => "string",
    ]),
    CURLOPT_HTTPHEADER => [
      "Authorization: Bearer <token>",
      "Content-Type: application/json",
    ],
  ]);

  $response = curl_exec($curl);
  curl_close($curl);

  echo $response;
  ```

  ```go Go theme={null}
  package main

  import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
    "io/ioutil"
  )

  func main() {
    payload, _ := json.Marshal(map[string]string{
      "fieldName": "company",
      "fieldType": "string",
    })

    req, _ := http.NewRequest("POST", "https://api.autosend.com/v1/custom-fields", bytes.NewBuffer(payload))
    req.Header.Set("Authorization", "Bearer <token>")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()

    body, _ := ioutil.ReadAll(resp.Body)
    fmt.Println(string(body))
  }
  ```

  ```java Java theme={null}
  import java.net.URI;
  import java.net.http.HttpClient;
  import java.net.http.HttpRequest;
  import java.net.http.HttpResponse;

  public class Main {
    public static void main(String[] args) throws Exception {
      HttpClient client = HttpClient.newHttpClient();

      String body = """
        {
          "fieldName": "company",
          "fieldType": "string"
        }
        """;

      HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://api.autosend.com/v1/custom-fields"))
        .header("Authorization", "Bearer <token>")
        .header("Content-Type", "application/json")
        .POST(HttpRequest.BodyPublishers.ofString(body))
        .build();

      HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
      System.out.println(response.body());
    }
  }
  ```

  ```ruby Ruby theme={null}
  require "net/http"
  require "uri"
  require "json"

  uri = URI.parse("https://api.autosend.com/v1/custom-fields")
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true

  request = Net::HTTP::Post.new(uri)
  request["Authorization"] = "Bearer <token>"
  request["Content-Type"] = "application/json"
  request.body = JSON.dump({
    fieldName: "company",
    fieldType: "string"
  })

  response = http.request(request)
  puts response.body
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "message": "Custom field created successfully",
    "data": {
      "id": "6960953e729f65f154369408",
      "fieldName": "company",
      "fieldType": "string",
      "projectId": "229f1f77bcf86cd9273048038",
      "createdAt": "2026-01-09T05:42:22.171Z",
      "updatedAt": "2026-01-09T05:42:22.171Z"
    }
  }
  ```
</ResponseExample>

### Authorizations

<ParamField path="Authorizations" type="string | header" required>
  Bearer authentication header of the form Bearer `<token>`, where `<token>` is your auth token.
</ParamField>

#### Body Parameters

<ParamField body="fieldName" type="string" required>
  The programmatic name for the custom field. Must be unique within the project. Cannot be one of the reserved names: `firstName`, `first_name`, `lastName`, `last_name`, `email`, `mobile`, `unsubscribed`, `unsubscribe`, `unsubscribe_groups`, `unsubscribe_preferences`, `userId`, `externalId`, `createdAt`, `updatedAt`, `contactLists`, `address`, `address_line_1`, `address_line_2`, `city`, `state`, `zip`, `country`.
</ParamField>

<ParamField body="fieldType" type="string" required>
  The data type of the custom field. Must be one of: `string`, `number`, `boolean`, `date`.
</ParamField>

<ParamField body="description" type="string">
  A human-readable description of what the field represents.
</ParamField>

<ParamField body="defaultValue" type="string">
  A fallback value used when a contact does not have an explicit value for this field.
</ParamField>

### Response

<span className="text-sm">Custom field created successfully</span>

<ResponseField name="success" type="boolean">
  Indicates whether the request was successful.
</ResponseField>

<ResponseField name="message" type="string">
  Confirmation message.

  Example: `"Custom field created successfully"`
</ResponseField>

<ResponseField name="data" type="object">
  The created custom field.

  <Expandable title="data">
    <ResponseField name="data.id" type="string">
      Unique identifier of the custom field.
    </ResponseField>

    <ResponseField name="data.fieldName" type="string">
      The programmatic name of the custom field.
    </ResponseField>

    <ResponseField name="data.fieldType" type="string">
      The data type: `string`, `number`, `boolean`, or `date`.
    </ResponseField>

    <ResponseField name="data.projectId" type="string">
      The project this custom field belongs to.
    </ResponseField>

    <ResponseField name="data.createdAt" type="string">
      ISO 8601 timestamp when the field was created.
    </ResponseField>

    <ResponseField name="data.updatedAt" type="string">
      ISO 8601 timestamp when the field was last updated.
    </ResponseField>
  </Expandable>
</ResponseField>


## OpenAPI

````yaml POST /custom-fields
openapi: 3.1.0
info:
  title: Custom Fields API
  description: >-
    API for managing custom contact fields in an Autosend project. Custom fields
    let you define dynamic attributes that are attached to every contact in your
    project. Reserved built-in field names cannot be used when creating custom
    fields.
  version: 1.0.0
servers:
  - url: https://api.autosend.com/v1
security:
  - bearerAuth: []
paths:
  /custom-fields:
    post:
      summary: Create Custom Field
      description: >-
        Creates a new custom field for the authenticated project. The
        `fieldName` must be unique within the project and must not conflict with
        any reserved built-in field name.
components: {}

````