Pipedrive PersonFields API

openapi: 3.0.1
info:
  title: Pipedrive API v1 Activities PersonFields API
  version: 1.0.0
  description: 'Activities are appointments/tasks/events on a calendar that can be associated with a deal, a lead, a person and an organization. Activities can be of different type (such as call, meeting, lunch or a custom type - see ActivityTypes object) and can be assigned to a particular user. Note that activities can also be created without a specific date/time.

    '
servers:
- url: https://api.pipedrive.com/v1
tags:
- name: PersonFields
  description: 'Person fields represent the near-complete schema for a person in the context of the company of the authorized user. Each company can have a different schema for their persons, with various custom fields. In the context of using person fields as a schema for defining the data fields of a person, it must be kept in mind that some types of custom fields can have additional data fields which are not separate person fields per se. Such is the case with monetary, daterange and timerange fields – each of these fields will have one additional data field in addition to the one presented in the context of person fields. For example, if there is a monetary field with the key `ffk9s9` stored on the account, `ffk9s9` would hold the numeric value of the field, and `ffk9s9_currency` would hold the ISO currency code that goes along with the numeric value. To find out which data fields are available, fetch one person and list its keys.

    '
paths:
  /personFields:
    get:
      summary: Get all person fields
      description: Returns data about all person fields.<br>If a company uses the [Campaigns product](https://pipedrive.readme.io/docs/campaigns-in-pipedrive-api), then this endpoint will also return the `data.marketing_status` field.
      x-token-cost: 20
      operationId: getPersonFields
      parameters:
      - in: query
        name: start
        description: Pagination start
        schema:
          type: integer
          default: 0
      - in: query
        name: limit
        description: Items shown per page
        schema:
          type: integer
      tags:
      - PersonFields
      security:
      - api_key: []
      - oauth2:
        - contacts:read
        - contacts:full
        - contact-fields:full
        - admin
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                title: GetFieldsResponse
                allOf:
                - title: baseResponse
                  type: object
                  properties:
                    success:
                      type: boolean
                      description: If the response is successful or not
                - title: FieldsResponse
                - type: object
                  properties:
                    data:
                      type: array
                      items:
                        type: object
                        title: GetField
                        allOf:
                        - title: Field
                          type: object
                          properties:
                            id:
                              type: integer
                              nullable: true
                              description: The ID of the field. Value is `null` in case of subfields.
                            key:
                              type: string
                              description: The key of the field. For custom fields this is generated upon creation.
                            name:
                              type: string
                              description: The name of the field
                            order_nr:
                              type: integer
                              description: The order number of the field
                            field_type:
                              allOf:
                              - type: string
                                enum:
                                - address
                                - date
                                - daterange
                                - double
                                - enum
                                - monetary
                                - org
                                - people
                                - phone
                                - set
                                - text
                                - time
                                - timerange
                                - user
                                - varchar
                                - varchar_auto
                                - visible_to
                                description: The type of the field<table><tr><th>Value</th><th>Description</th></tr><tr><td>`address`</td><td>Address field</td></tr><tr><td>`date`</td><td>Date (format YYYY-MM-DD)</td></tr><tr><td>`daterange`</td><td>Date-range field (has a start date and end date value, both YYYY-MM-DD)</td></tr><tr><td>`double`</td><td>Numeric value</td></tr><tr><td>`enum`</td><td>Options field with a single possible chosen option</td></tr><tr></tr><tr><td>`monetary`</td><td>Monetary field (has a numeric value and a currency value)</td></tr><tr><td>`org`</td><td>Organization field (contains an organization ID which is stored on the same account)</td></tr><tr><td>`people`</td><td>Person field (contains a person ID which is stored on the same account)</td></tr><tr><td>`phone`</td><td>Phone field (up to 255 numbers and/or characters)</td></tr><tr><td>`set`</td><td>Options field with a possibility of having multiple chosen options</td></tr><tr><td>`text`</td><td>Long text (up to 65k characters)</td></tr><tr><td>`time`</td><td>Time field (format HH:MM:SS)</td></tr><tr><td>`timerange`</td><td>Time-range field (has a start time and end time value, both HH:MM:SS)</td></tr><tr><td>`user`</td><td>User field (contains a user ID of another Pipedrive user)</td></tr><tr><td>`varchar`</td><td>Text (up to 255 characters)</td></tr><tr><td>`varchar_auto`</td><td>Autocomplete text (up to 255 characters)</td></tr><tr><td>`visible_to`</td><td>System field that keeps item's visibility setting</td></tr></table>
                            add_time:
                              type: string
                              format: date-time
                              description: The creation time of the field
                            update_time:
                              type: string
                              format: date-time
                              nullable: true
                              description: The update time of the field
                            last_updated_by_user_id:
                              type: integer
                              nullable: true
                              description: The ID of the user who created or most recently updated the field, only applicable for custom fields
                            created_by_user_id:
                              type: integer
                              nullable: true
                              description: The ID of the user who created the field
                            active_flag:
                              type: boolean
                              description: The active flag of the field
                            edit_flag:
                              type: boolean
                              description: The edit flag of the field
                            index_visible_flag:
                              type: boolean
                              description: Not used
                            details_visible_flag:
                              type: boolean
                              description: Not used
                            add_visible_flag:
                              type: boolean
                              description: Not used
                            important_flag:
                              type: boolean
                              description: Not used
                            bulk_edit_allowed:
                              type: boolean
                              description: Whether or not the field of an item can be edited in bulk
                            searchable_flag:
                              type: boolean
                              description: Whether or not items can be searched by this field
                            filtering_allowed:
                              type: boolean
                              description: Whether or not items can be filtered by this field
                            sortable_flag:
                              type: boolean
                              description: Whether or not items can be sorted by this field
                            mandatory_flag:
                              type: boolean
                              description: Whether or not the field is mandatory
                            options:
                              type: array
                              nullable: true
                              items:
                                type: object
                              description: The options of the field. When there are no options, `null` is returned.
                            options_deleted:
                              type: array
                              items:
                                type: object
                              description: The deleted options of the field. Only present when there is at least 1 deleted option.
                            is_subfield:
                              type: boolean
                              description: Whether or not the field is a subfield of another field. Only present if field is subfield.
                            subfields:
                              type: array
                              items:
                                type: object
                              description: The subfields of the field. Only present when the field has subfields.
                        - type: object
                          properties:
                            field_type:
                              type: string
                              enum:
                              - boolean
                              - double
                              - int
                              - json
                              - date
                              - daterange
                              - time
                              - timerange
                              - text
                              - varchar
                              - varchar_auto
                              - varchar_options
                              - address
                              - enum
                              - monetary
                              - phone
                              - set
                              - activity
                              - deal
                              - lead
                              - org
                              - people
                              - pipeline
                              - product
                              - project
                              - stage
                              - user
                              - billing_frequency
                              - picture
                              - price_list
                              - projects_board
                              - projects_phase
                              - status
                              - visible_to
                              description: List of all possible field types
                    additional_data:
                      description: The additional data of the list
                      type: object
                      properties:
                        start:
                          type: integer
                          description: Pagination start
                        limit:
                          type: integer
                          description: Items shown per page
                        more_items_in_collection:
                          type: boolean
                          description: If there are more list items in the collection than displayed or not
              example:
                success: true
                data:
                - id: 1
                  key: title
                  name: Title
                  order_nr: 2
                  field_type: varchar
                  add_time: '2019-02-04 13:58:03'
                  update_time: '2019-02-04 13:58:03'
                  last_updated_by_user_id: 1
                  created_by_user_id: 1
                  active_flag: true
                  edit_flag: false
                  index_visible_flag: true
                  details_visible_flag: true
                  add_visible_flag: true
                  important_flag: false
                  bulk_edit_allowed: true
                  searchable_flag: false
                  filtering_allowed: true
                  sortable_flag: true
                  options: null
                  mandatory_flag: true
                - id: 2
                  key: 9dc80c50d78a15643bfc4ca79d76156a73a1ca0e
                  name: Customer Type
                  order_nr: 1
                  field_type: enum
                  add_time: '2019-02-04 13:58:03'
                  update_time: '2019-02-04 13:58:03'
                  last_updated_by_user_id: 1
                  created_by_user_id: 1
                  active_flag: true
                  edit_flag: true
                  index_visible_flag: true
                  details_visible_flag: true
                  add_visible_flag: false
                  important_flag: false
                  bulk_edit_allowed: true
                  searchable_flag: false
                  filtering_allowed: true
                  sortable_flag: true
                  options:
                  - id: 190
                    label: Private person
                  - id: 191
                    label: Company
                  - id: 192
                    label: Government
                  mandatory_flag: true
                additional_data:
                  pagination:
                    start: 0
                    limit: 100
                    more_items_in_collection: false
    post:
      summary: Add a new person field
      description: Adds a new person field. For more information, see the tutorial for <a href="https://pipedrive.readme.io/docs/adding-a-new-custom-field" target="_blank" rel="noopener noreferrer">adding a new custom field</a>.
      x-token-cost: 10
      operationId: addPersonField
      tags:
      - PersonFields
      security:
      - api_key: []
      - oauth2:
        - contact-fields:full
        - admin
      requestBody:
        content:
          application/json:
            schema:
              title: createFieldRequest
              allOf:
              - type: object
                required:
                - name
                properties:
                  name:
                    type: string
                    description: The name of the field
                  options:
                    type: array
                    items:
                      type: object
                    description: 'When `field_type` is either set or enum, possible options must be supplied as a JSON-encoded sequential array of objects. Example: `[{"label":"New Item"}]`'
                  add_visible_flag:
                    type: boolean
                    default: true
                    description: Whether the field is available in the 'add new' modal or not (both in the web and mobile app)
              - type: object
                required:
                - field_type
                properties:
                  field_type:
                    type: string
                    enum:
                    - address
                    - date
                    - daterange
                    - double
                    - enum
                    - monetary
                    - org
                    - people
                    - phone
                    - set
                    - text
                    - time
                    - timerange
                    - user
                    - varchar
                    - varchar_auto
                    - visible_to
                    description: The type of the field<table><tr><th>Value</th><th>Description</th></tr><tr><td>`address`</td><td>Address field</td></tr><tr><td>`date`</td><td>Date (format YYYY-MM-DD)</td></tr><tr><td>`daterange`</td><td>Date-range field (has a start date and end date value, both YYYY-MM-DD)</td></tr><tr><td>`double`</td><td>Numeric value</td></tr><tr><td>`enum`</td><td>Options field with a single possible chosen option</td></tr><tr></tr><tr><td>`monetary`</td><td>Monetary field (has a numeric value and a currency value)</td></tr><tr><td>`org`</td><td>Organization field (contains an organization ID which is stored on the same account)</td></tr><tr><td>`people`</td><td>Person field (contains a person ID which is stored on the same account)</td></tr><tr><td>`phone`</td><td>Phone field (up to 255 numbers and/or characters)</td></tr><tr><td>`set`</td><td>Options field with a possibility of having multiple chosen options</td></tr><tr><td>`text`</td><td>Long text (up to 65k characters)</td></tr><tr><td>`time`</td><td>Time field (format HH:MM:SS)</td></tr><tr><td>`timerange`</td><td>Time-range field (has a start time and end time value, both HH:MM:SS)</td></tr><tr><td>`user`</td><td>User field (contains a user ID of another Pipedrive user)</td></tr><tr><td>`varchar`</td><td>Text (up to 255 characters)</td></tr><tr><td>`varchar_auto`</td><td>Autocomplete text (up to 255 characters)</td></tr><tr><td>`visible_to`</td><td>System field that keeps item's visibility setting</td></tr></table>
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                title: GetFieldResponse
                allOf:
                - title: baseResponse
                  type: object
                  properties:
                    success:
                      type: boolean
                      description: If the response is successful or not
                - type: object
                  properties:
                    data:
                      type: object
                      title: GetField
                      allOf:
                      - title: Field
                        type: object
                        properties:
                          id:
                            type: integer
                            nullable: true
                            description: The ID of the field. Value is `null` in case of subfields.
                          key:
                            type: string
                            description: The key of the field. For custom fields this is generated upon creation.
                          name:
                            type: string
                            description: The name of the field
                          order_nr:
                            type: integer
                            description: The order number of the field
                          field_type:
                            allOf:
                            - type: string
                              enum:
                              - address
                              - date
                              - daterange
                              - double
                              - enum
                              - monetary
                              - org
                              - people
                              - phone
                              - set
                              - text
                              - time
                              - timerange
                              - user
                              - varchar
                              - varchar_auto
                              - visible_to
                              description: The type of the field<table><tr><th>Value</th><th>Description</th></tr><tr><td>`address`</td><td>Address field</td></tr><tr><td>`date`</td><td>Date (format YYYY-MM-DD)</td></tr><tr><td>`daterange`</td><td>Date-range field (has a start date and end date value, both YYYY-MM-DD)</td></tr><tr><td>`double`</td><td>Numeric value</td></tr><tr><td>`enum`</td><td>Options field with a single possible chosen option</td></tr><tr></tr><tr><td>`monetary`</td><td>Monetary field (has a numeric value and a currency value)</td></tr><tr><td>`org`</td><td>Organization field (contains an organization ID which is stored on the same account)</td></tr><tr><td>`people`</td><td>Person field (contains a person ID which is stored on the same account)</td></tr><tr><td>`phone`</td><td>Phone field (up to 255 numbers and/or characters)</td></tr><tr><td>`set`</td><td>Options field with a possibility of having multiple chosen options</td></tr><tr><td>`text`</td><td>Long text (up to 65k characters)</td></tr><tr><td>`time`</td><td>Time field (format HH:MM:SS)</td></tr><tr><td>`timerange`</td><td>Time-range field (has a start time and end time value, both HH:MM:SS)</td></tr><tr><td>`user`</td><td>User field (contains a user ID of another Pipedrive user)</td></tr><tr><td>`varchar`</td><td>Text (up to 255 characters)</td></tr><tr><td>`varchar_auto`</td><td>Autocomplete text (up to 255 characters)</td></tr><tr><td>`visible_to`</td><td>System field that keeps item's visibility setting</td></tr></table>
                          add_time:
                            type: string
                            format: date-time
                            description: The creation time of the field
                          update_time:
                            type: string
                            format: date-time
                            nullable: true
                            description: The update time of the field
                          last_updated_by_user_id:
                            type: integer
                            nullable: true
                            description: The ID of the user who created or most recently updated the field, only applicable for custom fields
                          created_by_user_id:
                            type: integer
                            nullable: true
                            description: The ID of the user who created the field
                          active_flag:
                            type: boolean
                            description: The active flag of the field
                          edit_flag:
                            type: boolean
                            description: The edit flag of the field
                          index_visible_flag:
                            type: boolean
                            description: Not used
                          details_visible_flag:
                            type: boolean
                            description: Not used
                          add_visible_flag:
                            type: boolean
                            description: Not used
                          important_flag:
                            type: boolean
                            description: Not used
                          bulk_edit_allowed:
                            type: boolean
                            description: Whether or not the field of an item can be edited in bulk
                          searchable_flag:
                            type: boolean
                            description: Whether or not items can be searched by this field
                          filtering_allowed:
                            type: boolean
                            description: Whether or not items can be filtered by this field
                          sortable_flag:
                            type: boolean
                            description: Whether or not items can be sorted by this field
                          mandatory_flag:
                            type: boolean
                            description: Whether or not the field is mandatory
                          options:
                            type: array
                            nullable: true
                            items:
                              type: object
                            description: The options of the field. When there are no options, `null` is returned.
                          options_deleted:
                            type: array
                            items:
                              type: object
                            description: The deleted options of the field. Only present when there is at least 1 deleted option.
                          is_subfield:
                            type: boolean
                            description: Whether or not the field is a subfield of another field. Only present if field is subfield.
                          subfields:
                            type: array
                            items:
                              type: object
                            description: The subfields of the field. Only present when the field has subfields.
                      - type: object
                        properties:
                          field_type:
                            type: string
                            enum:
                            - boolean
                            - double
                            - int
                            - json
                            - date
                            - daterange
                            - time
                            - timerange
                            - text
                            - varchar
                            - varchar_auto
                            - varchar_options
                            - address
                            - enum
                            - monetary
                            - phone
                            - set
                            - activity
                            - deal
                            - lead
                            - org
                            - people
                            - pipeline
                            - product
                            - project
                            - stage
                            - user
                            - billing_frequency
                            - picture
                            - price_list
                            - projects_board
                            - projects_phase
                            - status
                            - visible_to
                            description: List of all possible field types
              example:
                success: true
                data:
                  id: 2
                  key: 9dc80c50d78a15643bfc4ca79d76156a73a1ca0e
                  name: Customer Type
                  order_nr: 1
                  field_type: enum
                  add_time: '2019-02-04 13:58:03'
                  update_time: '2019-02-04 13:58:03'
                  last_updated_by_user_id: 1
                  created_by_user_id: 1
                  active_flag: true
                  edit_flag: true
                  index_visible_flag: true
                  details_visible_flag: true
                  add_visible_flag: false
                  important_flag: false
                  bulk_edit_allowed: true
                  searchable_flag: false
                  filtering_allowed: true
                  sortable_flag: true
                  options:
                  - id: 190
                    label: Private person
                  - id: 191
                    label: Company
                  - id: 192
                    label: Government
                  mandatory_flag: true
    delete:
      summary: Delete multiple person fields in bulk
      description: Marks multiple fields as deleted.
      x-token-cost: 10
      operationId: deletePersonFields
      tags:
      - PersonFields
      security:
      - api_key: []
      - oauth2:
        - contact-fields:full
        - admin
      parameters:
      - in: query
        name: ids
        schema:
          type: string
        required: true
        description: The comma-separated field IDs to delete
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                title: DeleteFieldsResponse
                allOf:
                - title: baseResponse
                  type: object
                  properties:
                    success:
                      type: boolean
                      description: If the response is successful or not
                - type: object
                  properties:
                    data:
                      type: object
                      properties:
                        id:
                          type: array
                          items:
                            type: integer
                          description: The list of deleted field IDs
              example:
                success: true
                data:
                  id:
                  - 123
                  - 456
  /personFields/{id}:
    get:
      summary: Get one person field
      description: Returns data about a specific person field.
      x-token-cost: 2
      operationId: getPersonField
      tags:
      - PersonFields
      security:
      - api_key: []
      - oauth2:
        - contacts:read
        - contacts:full
        - contact-fields:full
        - admin
      parameters:
      - in: path
        name: id
        description: The ID of the field
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                title: GetFieldResponse
                allOf:
                - title: baseResponse
                  type: object
                  properties:
                    success:
                      type: boolean
                      description: If the response is successful or not
                - type: object
                  properties:
                    data:
                      type: object
                      title: GetField
                      allOf:
                      - title: Field
                        type: object
                        properties:
                          id:
                            type: integer
                            nullable: true
                            description: The ID of the field. Value is `null` in case of subfields.
                          key:
                            type: string
                            description: The key of the field. For custom fields this is generated upon creation.
                          name:
                            type: string
                            description: The name of the field
                          order_nr:
                            type: integer
                            description: The order number of the field
                          field_type:
                            allOf:
                            - type: string
                              enum:
                              - address
                              - date
                              - daterange
                              - double
                              - enum
                              - monetary
                              - org
                              - people
                              - phone
                              - set
                              - text
                              - time
                              - timerange
                              - user
                              - varchar
                              - varchar_auto
                              - visible_to
                              description: The type of the field<table><tr><th>Value</th><th>Description</th></tr><tr><td>`address`</td><td>Address field</td></tr><tr><td>`date`</td><td>Date (format YYYY-MM-DD)</td></tr><tr><td>`daterange`</td><td>Date-range field (has a start date and end date va

# --- truncated at 32 KB (86 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/pipedrive/refs/heads/main/openapi/pipedrive-personfields-api-openapi.yml