> ## Documentation Index > Fetch the complete documentation index at: https://docs.connectadesk.com/llms.txt > Use this file to discover all available pages before exploring further. # Update custom field > On a system field, the key, application and type are ignored. Only the name, description and group can be changed. ## OpenAPI ````yaml /api-reference/openapi.en.yaml put /custom-fields/{id} openapi: 3.0.3 info: title: Connecta DESK Public API version: 1.0.0 description: >- Public API of Connecta DESK, available at `/api/v1`. Access uses a token generated in the tokens module. Each token has permissions per **module × method**, and every list read is paginated. ## Authentication ``` Authorization: Bearer sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6 ``` The token belongs to a **company**, not to a user. The company used is always the token's company, so sending `companyId` in the body has no effect. A missing, invalid, revoked or expired token gets the same `401` response. ## Order of checks 1. **token** → `401` 2. **active company** → `403` 3. **API enabled on the plan** → `403 ERR_API_NOT_ENABLED` (does not apply to on-premise) 4. **company rate limit** → `429` 5. **token permission** → `403 ERR_API_FORBIDDEN_SCOPE` ## User ids Every user id in the API is the user's id **in this company**, the same one `GET /users` returns. This applies to what the API returns (`user.id`, `assignedTo.id`, `userCreated.id`) and to what it accepts (`userId`, `userIds`, `assignedToUserId` and the `{id}` in user routes). The same person can work in several companies, with a different name and profile in each one, and has a different id in each company. An id that does not belong to this company returns `404`, with the same message as an id that does not exist. ## Pagination Every list `GET` is paginated. The `meta` contains only `page`, `perPage` and `hasMore`, without the total number of records. To go through everything, keep advancing `page` while `hasMore` is `true`. ## Idempotency Optional on `POST`/`PUT`, through the `Idempotency-Key` header. If you repeat the call with the same key and the same body, you get the stored response (with `Idempotent-Replay: true`). With the same key and a different body, the response is `409`. servers: - url: https://api.connectadesk.com/api/v1 description: Production security: - apiToken: [] tags: - name: contacts description: Contact records, extra fields and marketing source. - name: tickets x-displayName: Tickets description: Opening, transferring, closing and wrap-up of tickets. - name: messages description: Asynchronous sending and reading of messages. - name: tags description: Tags and their link to tickets. - name: queues description: Service queues and their agents. - name: wrapups description: Wrap-up types. - name: users description: Agents and administrators. - name: schedules description: Scheduled messages. - name: quick-messages description: Quick replies. - name: campaigns description: Bulk sending. - name: crm description: Boards, stages, cards and metrics. - name: channels description: Channels (read only). - name: reports description: Reports and dashboards. - name: products description: Product catalog, categories and sales performance. - name: custom-fields description: Custom fields for contacts and cards, plus company-wide global variables. - name: profiles description: Company permission profiles (read only). - name: webchat description: >- Native webchat from your own system: open a visitor session, send and read messages. The token needs the `webchat` scope (GET and POST). paths: /custom-fields/{id}: parameters: - name: id in: path required: true schema: type: integer put: tags: - custom-fields summary: Update custom field description: >- On a system field, the key, application and type are ignored. Only the name, description and group can be changed. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CustomFieldInput' responses: '200': description: OK content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/CustomField' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' components: schemas: CustomFieldInput: type: object required: - name - application - type properties: name: type: string maxLength: 60 description: Display name. example: Plano key: type: string maxLength: 40 description: >- If you leave it out, the key is generated from the name, in `minusculas_com_underline` format (lowercase with underscores). example: plano description: type: string nullable: true maxLength: 120 description: Description of the custom field. application: type: string enum: - contact - card description: >- Where the field applies: `contact` for contacts, `card` for CRM cards. type: type: string enum: - text - number - currency - date - select - boolean - email - phone - link - textarea description: >- Type of value accepted. It defines the validation applied on each save: | value | accepts | | --- | --- | | `text` | Short text, one line. | | `number` | Number. | | `currency` | Monetary amount. | | `date` | Date. | | `select` | One of the options registered on the field itself. | | `boolean` | Yes or no. | | `email` | Email, with its format validated. | | `phone` | Phone number. | | `link` | URL. | | `textarea` | Long text, several lines. | groupName: type: string nullable: true description: >- Group the field belongs to in the form. Fields in the same group appear together. example: Comercial isPublic: type: boolean default: true description: >- Makes the field visible to all agents. When false, only users with permission can see it. alwaysVisible: type: boolean default: false description: Shows the field on the record even when no value is filled in. options: type: array description: List of options. Required when `type` is `select`. items: type: object required: - name properties: name: type: string maxLength: 40 description: Display name. example: Plano color: type: string nullable: true description: Color in hexadecimal, with `#`. example: '#6941C6' CustomField: type: object properties: id: type: integer key: type: string description: Identifier used in flows and messages, as in `{{tipo_de_cliente}}`. example: tipo_de_cliente name: type: string description: Display name. example: Plano description: type: string nullable: true description: Description of the custom field. application: type: string enum: - contact - card description: >- Where the field applies: `contact` for contacts, `card` for CRM cards. type: type: string enum: - text - number - currency - date - select - boolean - email - phone - link - textarea description: >- Type of value accepted. It defines the validation applied on each save: | value | accepts | | --- | --- | | `text` | Short text, one line. | | `number` | Number. | | `currency` | Monetary amount. | | `date` | Date. | | `select` | One of the options registered on the field itself. | | `boolean` | Yes or no. | | `email` | Email, with its format validated. | | `phone` | Phone number. | | `link` | URL. | | `textarea` | Long text, several lines. | groupName: type: string nullable: true description: >- Group the field belongs to in the form. Fields in the same group appear together. example: Comercial isPublic: type: boolean description: When false, the field is visible only to users with permission. alwaysVisible: type: boolean description: Shows the field on the record even when it has no value. isSystem: type: boolean description: >- System field. Its key, application and type cannot be changed, and the field cannot be deleted. order: type: integer example: desc options: type: array description: List of options. Present when `type` is `select`. items: $ref: '#/components/schemas/CustomFieldOption' createdAt: type: string format: date-time updatedAt: type: string format: date-time example: id: 44 key: tipo_de_cliente name: Tipo de cliente description: Commercial classification used in the service playbook. application: contact type: select groupName: Comercial isPublic: true alwaysVisible: true isSystem: false order: 2 options: - id: 91 name: Varejo color: '#0E7490' order: 0 - id: 92 name: Atacado color: '#6941C6' order: 1 createdAt: '2026-06-09T09:30:00.000Z' updatedAt: '2026-08-14T16:05:00.000Z' CustomFieldOption: type: object properties: id: type: integer name: type: string description: Display name. color: type: string nullable: true description: Color in hexadecimal, with `#`. example: '#6941C6' order: type: integer example: desc Error: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string description: Fixed error code, so your system can handle each case. example: ERR_API_FORBIDDEN_SCOPE message: type: string details: {} responses: BadRequest: description: Invalid request body. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: ERR_API_VALIDATION message: O campo `number` é obrigatório. Unauthorized: description: Token missing, invalid, revoked or expired. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: ERR_API_UNAUTHORIZED message: Token de API ausente ou inválido. Forbidden: description: >- Inactive company, API not enabled on the plan, or insufficient permission. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: ERR_API_FORBIDDEN_SCOPE message: >- O token não tem permissão para este método neste módulo. A mensagem real nomeia os dois. NotFound: description: >- The resource does not exist or belongs to another company. For security, the response is the same in both cases. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: ERR_API_NOT_FOUND message: Registro não encontrado. Conflict: description: '`Idempotency-Key` conflict.' content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: ERR_API_IDEMPOTENCY_KEY_REUSED message: Idempotency-Key já usada com um corpo diferente. UnprocessableEntity: description: >- The body is well formed, but a required field is missing or a value is not accepted. For example, `application` other than `contact`/`card`, an empty `orderedIds` or a blank `name`. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: ERR_API_VALIDATION message: >- O parâmetro `application` é obrigatório e aceita "contact" ou "card". securitySchemes: apiToken: type: http scheme: bearer description: API token in the `sk_live_…` format. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.