> For the complete documentation index, see [llms.txt](https://docs.usepylon.com/pylon-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.usepylon.com/pylon-docs/developer/api/api-reference/custom-fields.md). # Custom Fields ## Get all custom fields > Returns all custom field definitions for the specified object type.\ > \ > \*\*Rate limit:\*\* 60 requests per minute ```json {"openapi":"3.0.3","info":{"title":"Pylon API.","version":"1.0.0"},"servers":[{"url":"https://api.usepylon.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"description":"Authorization: Bearer ","scheme":"bearer","type":"http"}},"responses":{"GetCustomFieldsResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetCustomFieldsResponseBody"}}},"description":""},"BadRequestApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The request was invalid or could not be completed."},"ErrorApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":""},"InternalServerErrorApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"An unexpected internal error occurred."}},"schemas":{"GetCustomFieldsResponseBody":{"properties":{"data":{"description":"The data payload of the response.","items":{"$ref":"#/components/schemas/CustomFieldDefinition"},"type":"array"},"pagination":{"$ref":"#/components/schemas/Pagination"},"request_id":{"description":"The request ID for tracking.","type":"string"}},"type":"object"},"CustomFieldDefinition":{"properties":{"created_at":{"description":"When the custom field was created.","type":"string"},"default_value":{"description":"The default value for single-valued custom fields.","type":"string"},"default_values":{"description":"The default values for multi-valued custom fields.","items":{"type":"string"},"type":"array"},"description":{"description":"The description of the custom field.","type":"string"},"id":{"description":"The ID of the custom field.","type":"string"},"is_read_only":{"description":"Whether the custom field is read only. Fields synced from apps and integrations are read-only.","type":"boolean"},"label":{"description":"The label of the custom field.","type":"string"},"number_metadata":{"$ref":"#/components/schemas/NumberMetadata"},"object_type":{"description":"The type of object this custom field is for. This can be a built-in or custom object type.","type":"string"},"select_metadata":{"$ref":"#/components/schemas/SelectMetadata"},"slug":{"description":"The slug of the custom field.","type":"string"},"source":{"description":"The source of the custom field.","type":"string"},"type":{"description":"The type of the custom field.","type":"string"},"updated_at":{"description":"When the custom field was last updated.","type":"string"}},"type":"object"},"NumberMetadata":{"properties":{"currency":{"description":"The currency of the number custom field.","type":"string"},"decimal_places":{"description":"The decimal places of the number custom field.","format":"int64","type":"integer"},"duration_display_format":{"description":"The display format for duration format (auto, minutes, hours, days, months, years).","type":"string"},"duration_input_unit":{"description":"The input unit for duration format (seconds, minutes, hours, days).","type":"string"},"format":{"description":"The format of the number custom field.","enum":["with_commas","percent","currency","duration"],"type":"string"}},"type":"object"},"SelectMetadata":{"properties":{"options":{"description":"The list options of the select custom field. This is only present for select and multiselect custom fields.","items":{"$ref":"#/components/schemas/CustomFieldDefinitionSelectOption"},"type":"array"}},"type":"object"},"CustomFieldDefinitionSelectOption":{"properties":{"ai_description":{"description":"The AI description of the option. This is used to help the AI understand when to select this option.","type":"string"},"label":{"description":"The label of the option.","type":"string"},"slug":{"description":"The slug of the option.","type":"string"}},"type":"object"},"Pagination":{"properties":{"cursor":{"description":"The cursor for the next page of results.","type":"string"},"has_next_page":{"description":"Indicates if there is a next page of results.","type":"boolean"}},"required":["cursor","has_next_page"],"type":"object"},"ErrorApiResponseBody":{"properties":{"errors":{"description":"The list of errors.","items":{"type":"string"},"type":"array"},"exists_id":{"description":"The ID of the object that already exists if this is a duplicate object error.","type":"string"},"request_id":{"description":"The request ID for tracking.","type":"string"}},"type":"object"}}},"paths":{"/custom-fields":{"get":{"description":"Returns all custom field definitions for the specified object type.\n\n**Rate limit:** 60 requests per minute","operationId":"GetCustomFields","parameters":[{"description":"The object type of the custom fields. Can be \"account\", \"issue\", \"contact\", \"task\", \"project\", \"meeting\", or \"opportunity\".","in":"query","name":"object_type","required":true,"schema":{"enum":["account","issue","contact","task","project","meeting","opportunity"],"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/GetCustomFieldsResponse"},"400":{"$ref":"#/components/responses/BadRequestApiResponse"},"404":{"$ref":"#/components/responses/ErrorApiResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorApiResponse"}},"summary":"Get all custom fields","tags":["custom-fields"]}}}} ``` ## Get a custom field by its ID > Returns a single custom field definition by ID.\ > \ > \*\*Rate limit:\*\* 60 requests per minute ```json {"openapi":"3.0.3","info":{"title":"Pylon API.","version":"1.0.0"},"servers":[{"url":"https://api.usepylon.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"description":"Authorization: Bearer ","scheme":"bearer","type":"http"}},"responses":{"GetCustomFieldResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetCustomFieldResponseBody"}}},"description":""},"BadRequestApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The request was invalid or could not be completed."},"ErrorApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":""},"InternalServerErrorApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"An unexpected internal error occurred."}},"schemas":{"GetCustomFieldResponseBody":{"properties":{"data":{"$ref":"#/components/schemas/CustomFieldDefinition"},"request_id":{"description":"The request ID for tracking.","type":"string"}},"type":"object"},"CustomFieldDefinition":{"properties":{"created_at":{"description":"When the custom field was created.","type":"string"},"default_value":{"description":"The default value for single-valued custom fields.","type":"string"},"default_values":{"description":"The default values for multi-valued custom fields.","items":{"type":"string"},"type":"array"},"description":{"description":"The description of the custom field.","type":"string"},"id":{"description":"The ID of the custom field.","type":"string"},"is_read_only":{"description":"Whether the custom field is read only. Fields synced from apps and integrations are read-only.","type":"boolean"},"label":{"description":"The label of the custom field.","type":"string"},"number_metadata":{"$ref":"#/components/schemas/NumberMetadata"},"object_type":{"description":"The type of object this custom field is for. This can be a built-in or custom object type.","type":"string"},"select_metadata":{"$ref":"#/components/schemas/SelectMetadata"},"slug":{"description":"The slug of the custom field.","type":"string"},"source":{"description":"The source of the custom field.","type":"string"},"type":{"description":"The type of the custom field.","type":"string"},"updated_at":{"description":"When the custom field was last updated.","type":"string"}},"type":"object"},"NumberMetadata":{"properties":{"currency":{"description":"The currency of the number custom field.","type":"string"},"decimal_places":{"description":"The decimal places of the number custom field.","format":"int64","type":"integer"},"duration_display_format":{"description":"The display format for duration format (auto, minutes, hours, days, months, years).","type":"string"},"duration_input_unit":{"description":"The input unit for duration format (seconds, minutes, hours, days).","type":"string"},"format":{"description":"The format of the number custom field.","enum":["with_commas","percent","currency","duration"],"type":"string"}},"type":"object"},"SelectMetadata":{"properties":{"options":{"description":"The list options of the select custom field. This is only present for select and multiselect custom fields.","items":{"$ref":"#/components/schemas/CustomFieldDefinitionSelectOption"},"type":"array"}},"type":"object"},"CustomFieldDefinitionSelectOption":{"properties":{"ai_description":{"description":"The AI description of the option. This is used to help the AI understand when to select this option.","type":"string"},"label":{"description":"The label of the option.","type":"string"},"slug":{"description":"The slug of the option.","type":"string"}},"type":"object"},"ErrorApiResponseBody":{"properties":{"errors":{"description":"The list of errors.","items":{"type":"string"},"type":"array"},"exists_id":{"description":"The ID of the object that already exists if this is a duplicate object error.","type":"string"},"request_id":{"description":"The request ID for tracking.","type":"string"}},"type":"object"}}},"paths":{"/custom-fields/{id}":{"get":{"description":"Returns a single custom field definition by ID.\n\n**Rate limit:** 60 requests per minute","operationId":"GetCustomField","parameters":[{"description":"The ID of the custom field.","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/GetCustomFieldResponse"},"400":{"$ref":"#/components/responses/BadRequestApiResponse"},"404":{"$ref":"#/components/responses/ErrorApiResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorApiResponse"}},"summary":"Get a custom field by its ID","tags":["custom-fields"]}}}} ``` ## Create a custom field > Creates a new custom field definition for the specified object type.\ > \ > \*\*Rate limit:\*\* 20 requests per minute ```json {"openapi":"3.0.3","info":{"title":"Pylon API.","version":"1.0.0"},"servers":[{"url":"https://api.usepylon.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"description":"Authorization: Bearer ","scheme":"bearer","type":"http"}},"schemas":{"CreateCustomFieldRequestBody":{"properties":{"default_value":{"description":"The default value for single-valued custom fields.","type":"string"},"default_values":{"description":"The default values for multi-valued custom fields.","items":{"type":"string"},"type":"array"},"description":{"description":"The description of the custom field.","type":"string"},"label":{"description":"The label of the custom field.","type":"string"},"object_type":{"description":"The object type of the custom field. Can be \"account\", \"issue\", \"contact\", \"task\", \"project\", \"meeting\", or \"opportunity\".","enum":["account","issue","contact","task","project","meeting","opportunity"],"type":"string"},"select_options":{"description":"The list options of the select custom field. This is only present for select and multiselect custom fields.","items":{"$ref":"#/components/schemas/CustomFieldDefinitionSelectOption"},"type":"array"},"slug":{"description":"The slug of the custom field.","type":"string"},"type":{"description":"The type of the custom field. Can be one of `text`, `number`, `decimal`, `boolean`, `date`, `datetime`, `user`, `url`, `select`, or `multiselect`.","type":"string"}},"required":["object_type","label","type"],"type":"object"},"CustomFieldDefinitionSelectOption":{"properties":{"ai_description":{"description":"The AI description of the option. This is used to help the AI understand when to select this option.","type":"string"},"label":{"description":"The label of the option.","type":"string"},"slug":{"description":"The slug of the option.","type":"string"}},"type":"object"},"CreateCustomFieldResponseBody":{"properties":{"data":{"$ref":"#/components/schemas/CustomFieldDefinition"},"request_id":{"description":"The request ID for tracking.","type":"string"}},"type":"object"},"CustomFieldDefinition":{"properties":{"created_at":{"description":"When the custom field was created.","type":"string"},"default_value":{"description":"The default value for single-valued custom fields.","type":"string"},"default_values":{"description":"The default values for multi-valued custom fields.","items":{"type":"string"},"type":"array"},"description":{"description":"The description of the custom field.","type":"string"},"id":{"description":"The ID of the custom field.","type":"string"},"is_read_only":{"description":"Whether the custom field is read only. Fields synced from apps and integrations are read-only.","type":"boolean"},"label":{"description":"The label of the custom field.","type":"string"},"number_metadata":{"$ref":"#/components/schemas/NumberMetadata"},"object_type":{"description":"The type of object this custom field is for. This can be a built-in or custom object type.","type":"string"},"select_metadata":{"$ref":"#/components/schemas/SelectMetadata"},"slug":{"description":"The slug of the custom field.","type":"string"},"source":{"description":"The source of the custom field.","type":"string"},"type":{"description":"The type of the custom field.","type":"string"},"updated_at":{"description":"When the custom field was last updated.","type":"string"}},"type":"object"},"NumberMetadata":{"properties":{"currency":{"description":"The currency of the number custom field.","type":"string"},"decimal_places":{"description":"The decimal places of the number custom field.","format":"int64","type":"integer"},"duration_display_format":{"description":"The display format for duration format (auto, minutes, hours, days, months, years).","type":"string"},"duration_input_unit":{"description":"The input unit for duration format (seconds, minutes, hours, days).","type":"string"},"format":{"description":"The format of the number custom field.","enum":["with_commas","percent","currency","duration"],"type":"string"}},"type":"object"},"SelectMetadata":{"properties":{"options":{"description":"The list options of the select custom field. This is only present for select and multiselect custom fields.","items":{"$ref":"#/components/schemas/CustomFieldDefinitionSelectOption"},"type":"array"}},"type":"object"},"ErrorApiResponseBody":{"properties":{"errors":{"description":"The list of errors.","items":{"type":"string"},"type":"array"},"exists_id":{"description":"The ID of the object that already exists if this is a duplicate object error.","type":"string"},"request_id":{"description":"The request ID for tracking.","type":"string"}},"type":"object"}},"responses":{"CreateCustomFieldResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCustomFieldResponseBody"}}},"description":""},"BadRequestApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The request was invalid or could not be completed."},"ErrorApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":""},"InternalServerErrorApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"An unexpected internal error occurred."}}},"paths":{"/custom-fields":{"post":{"description":"Creates a new custom field definition for the specified object type.\n\n**Rate limit:** 20 requests per minute","operationId":"CreateCustomField","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCustomFieldRequestBody"}}}},"responses":{"200":{"$ref":"#/components/responses/CreateCustomFieldResponse"},"400":{"$ref":"#/components/responses/BadRequestApiResponse"},"404":{"$ref":"#/components/responses/ErrorApiResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorApiResponse"}},"summary":"Create a custom field","tags":["custom-fields"]}}}} ``` ## Update a custom field > Updates a custom field definition. Only provided fields are modified.\ > \ > \*\*Rate limit:\*\* 20 requests per minute ```json {"openapi":"3.0.3","info":{"title":"Pylon API.","version":"1.0.0"},"servers":[{"url":"https://api.usepylon.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"description":"Authorization: Bearer ","scheme":"bearer","type":"http"}},"schemas":{"UpdateCustomFieldRequestBody":{"properties":{"default_value":{"description":"The default value for single-valued custom fields.","type":"string"},"default_values":{"description":"The default values for multi-valued custom fields.","items":{"type":"string"},"type":"array"},"description":{"description":"The description of the custom field.","type":"string"},"label":{"description":"The label of the custom field.","type":"string"},"select_options":{"description":"The list options of the select custom field. This is only present for select and multiselect custom fields.","items":{"$ref":"#/components/schemas/CustomFieldDefinitionSelectOption"},"type":"array"},"slug":{"description":"The slug of the custom field.","type":"string"}},"type":"object"},"CustomFieldDefinitionSelectOption":{"properties":{"ai_description":{"description":"The AI description of the option. This is used to help the AI understand when to select this option.","type":"string"},"label":{"description":"The label of the option.","type":"string"},"slug":{"description":"The slug of the option.","type":"string"}},"type":"object"},"UpdateCustomFieldResponseBody":{"properties":{"data":{"$ref":"#/components/schemas/CustomFieldDefinition"},"request_id":{"description":"The request ID for tracking.","type":"string"}},"type":"object"},"CustomFieldDefinition":{"properties":{"created_at":{"description":"When the custom field was created.","type":"string"},"default_value":{"description":"The default value for single-valued custom fields.","type":"string"},"default_values":{"description":"The default values for multi-valued custom fields.","items":{"type":"string"},"type":"array"},"description":{"description":"The description of the custom field.","type":"string"},"id":{"description":"The ID of the custom field.","type":"string"},"is_read_only":{"description":"Whether the custom field is read only. Fields synced from apps and integrations are read-only.","type":"boolean"},"label":{"description":"The label of the custom field.","type":"string"},"number_metadata":{"$ref":"#/components/schemas/NumberMetadata"},"object_type":{"description":"The type of object this custom field is for. This can be a built-in or custom object type.","type":"string"},"select_metadata":{"$ref":"#/components/schemas/SelectMetadata"},"slug":{"description":"The slug of the custom field.","type":"string"},"source":{"description":"The source of the custom field.","type":"string"},"type":{"description":"The type of the custom field.","type":"string"},"updated_at":{"description":"When the custom field was last updated.","type":"string"}},"type":"object"},"NumberMetadata":{"properties":{"currency":{"description":"The currency of the number custom field.","type":"string"},"decimal_places":{"description":"The decimal places of the number custom field.","format":"int64","type":"integer"},"duration_display_format":{"description":"The display format for duration format (auto, minutes, hours, days, months, years).","type":"string"},"duration_input_unit":{"description":"The input unit for duration format (seconds, minutes, hours, days).","type":"string"},"format":{"description":"The format of the number custom field.","enum":["with_commas","percent","currency","duration"],"type":"string"}},"type":"object"},"SelectMetadata":{"properties":{"options":{"description":"The list options of the select custom field. This is only present for select and multiselect custom fields.","items":{"$ref":"#/components/schemas/CustomFieldDefinitionSelectOption"},"type":"array"}},"type":"object"},"ErrorApiResponseBody":{"properties":{"errors":{"description":"The list of errors.","items":{"type":"string"},"type":"array"},"exists_id":{"description":"The ID of the object that already exists if this is a duplicate object error.","type":"string"},"request_id":{"description":"The request ID for tracking.","type":"string"}},"type":"object"}},"responses":{"UpdateCustomFieldResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCustomFieldResponseBody"}}},"description":""},"BadRequestApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"The request was invalid or could not be completed."},"ErrorApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":""},"InternalServerErrorApiResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponseBody"}}},"description":"An unexpected internal error occurred."}}},"paths":{"/custom-fields/{id}":{"patch":{"description":"Updates a custom field definition. Only provided fields are modified.\n\n**Rate limit:** 20 requests per minute","operationId":"UpdateCustomField","parameters":[{"description":"The ID of the custom field.","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCustomFieldRequestBody"}}}},"responses":{"200":{"$ref":"#/components/responses/UpdateCustomFieldResponse"},"400":{"$ref":"#/components/responses/BadRequestApiResponse"},"404":{"$ref":"#/components/responses/ErrorApiResponse"},"500":{"$ref":"#/components/responses/InternalServerErrorApiResponse"}},"summary":"Update a custom field","tags":["custom-fields"]}}}} ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.usepylon.com/pylon-docs/developer/api/api-reference/custom-fields.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.