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

# Delete a Synced Contact Field with the API

> Delete a contact field your sync defined, along with its stored values, so you can define the same key again with a new type or enum options.

A field's type cannot change after it is created, and enum options cannot be removed. To change either, delete the field with this endpoint, then send the new definition in the `fields` of your next [Upsert Synced Contact](/api-reference/contacts/upsert-contact) request. If your source sends field definitions with every upsert, update it to send the new definition first, or its next upsert creates the old field again.

Deleting a field also deletes the values stored for it on every contact. Contacts themselves are not affected. A contact has no value for the field again until your source syncs that contact with it.

To avoid that gap, define the new shape under a new key, sync contacts with values for it, then delete the old field once nothing uses it.

```bash theme={null}
curl -X DELETE 'https://api.usesimple.ai/api/v1/contacts/fields/lifecycle_stage' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

```json theme={null}
{
  "key": "lifecycle_stage",
  "deleted": true
}
```

Only fields defined through contact upsert can be deleted. The request is rejected, and nothing is deleted, when the field:

* is `name`, `email`, or `phone_number`, which returns `422`
* was created in Simple, which returns `409`
* is used by a contact segment or the call params mapping, which returns `409`. Remove it from the segment or mapping first.

The endpoint also returns `401` when authentication fails, `404` when your organization has no field with that key, and `422` when the key is invalid.


## OpenAPI

````yaml DELETE /contacts/fields/{fieldKey}
openapi: 3.1.0
info:
  title: Public API v1
  description: >-
    Public API v1 requiring API keys.


    **Timestamps:** All datetime fields in API responses are returned in UTC
    using ISO 8601 format (e.g., `2024-01-15T14:30:00Z`). When filtering by date
    parameters, provide timestamps in ISO 8601 format.
  version: 0.1.0
servers:
  - url: https://api.usesimple.ai/api/v1
    description: Production API Server
security: []
paths:
  /contacts/fields/{fieldKey}:
    delete:
      tags:
        - Contacts
      summary: Delete Synced Contact Field
      description: >-
        Delete a contact field definition a sync source created, together with
        the values stored for it on every contact, so a source can define the
        same key again with a new type or enum options.
      operationId: delete_synced_contact_field
      parameters:
        - name: fieldKey
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 63
            pattern: ^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$
          description: Key of the field to delete.
      responses:
        '200':
          description: The field was deleted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteSyncedContactFieldResponse'
        '401':
          description: Authentication failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
        '404':
          description: The organization has no field with this key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
        '409':
          description: >-
            The field was created in Simple, or a contact segment or the call
            params mapping uses it. Nothing is deleted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
        '422':
          description: The key is invalid or names the name, email, or phone_number field.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
      security:
        - APIKeyHeader: []
components:
  schemas:
    DeleteSyncedContactFieldResponse:
      type: object
      required:
        - key
        - deleted
      properties:
        key:
          type: string
          description: The key of the deleted field.
        deleted:
          type: boolean
          const: true
      title: Delete Synced Contact Field Response
    PublicApiError:
      type: object
      required:
        - status
        - success
        - error
        - errors
      properties:
        status:
          type: string
          const: error
        success:
          type: boolean
          const: false
        error:
          type: string
        errors:
          type: array
          items:
            type: string
      title: Public API Error
  securitySchemes:
    APIKeyHeader:
      type: http
      scheme: bearer
      description: 'Your API key, sent as `Authorization: Bearer YOUR_API_KEY`'

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.