--- updatedAt: 2026-04-21T09:29:18.000Z agentTools: projectIndex: https://partner.getpliant.com/llms.txt --- # Create Custom Field Create a new custom field for the organization. Custom fields can be used to store additional information on transactions. For example, you can create a custom field to store an internal identifier, a project name, or accounting related data. Custom fields can be of type `TEXT` or `SELECT`. `TEXT` custom fields can store any text value. `SELECT` custom fields can store a fixed set of options. Each new custom field is created `ACTIVE`. # OpenAPI definition ```json { "openapi": "3.0.1", "info": { "contact": { "name": "API Support", "email": "support@getpliant.com", "url": "https://www.getpliant.com" }, "title": "Pliant Partner API", "description": "Pliant Partner API", "version": "2.1.0", "license": { "name": "MIT", "url": "https://opensource.org/license/MIT" } }, "servers": [ { "url": "https://partner-api.getpliant.com/api", "description": "Pliant Production Server" }, { "url": "https://sandbox.partner-api.getpliant.com/api", "description": "Pliant Sandbox Server" }, { "url": "https://pci-api.getpliant.com", "description": "PCI Vault Production Server" }, { "url": "https://pci-sandbox.partner-api.getpliant.com", "description": "PCI Vault Sandbox Server" } ], "x-readme": { "explorer-enabled": false, "samples-languages": [ "curl", "java", "kotlin" ], "headers": [ { "key": "Pliant-API-Version", "value": "2.1.0" } ] }, "tags": [ { "name": "Custom Fields", "description": "This tag is for operations related to custom fields" } ], "paths": { "/transactions/custom-fields": { "post": { "summary": "Create Custom Field", "description": "Create a new custom field for the organization. Custom fields can be used to store additional information on transactions. For example, you can create a custom field to store an internal identifier, a project name, or accounting related data. Custom fields can be of type `TEXT` or `SELECT`. `TEXT` custom fields can store any text value. `SELECT` custom fields can store a fixed set of options. Each new custom field is created `ACTIVE`.", "tags": [ "Custom Fields" ], "operationId": "create-custom-field", "parameters": [ { "name": "organizationId", "required": true, "in": "query", "description": "The unique identifier of the organization to create the custom field for.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "label", "type", "automationType", "mandatoryOnAutomation", "mandatoryForExport" ], "properties": { "label": { "type": "string", "description": "The label of the custom field, displayed in the UI." }, "description": { "type": "string", "description": "The description of the custom field, displayed in the UI, optional." }, "defaultValue": { "type": "string", "description": "The default value of the custom field, optional." }, "type": { "type": "string", "description": "The type of the custom field.\n`TEXT` represents a custom field which can store any text value.\n`SELECT` represents a custom field which can store a fixed set of options.\n", "enum": [ "TEXT", "SELECT" ] }, "automationType": { "type": "string", "description": "The automation type of the custom field. For now only `CARD` is supported. This means, that the [custom fields](/docs/custom-fields-on-transactions) default value will be copied to every transaction made with the card the field is set on.", "enum": [ "CARD" ] }, "mandatoryOnAutomation": { "type": "boolean", "description": "If set to true, this means this custom field is mandatory to be filled with a default value on the level of the automation, here `CARD`." }, "mandatoryForExport": { "type": "boolean", "description": "If set to true, this means this custom field is mandatory to be filled on every transaction which should be exported with the Pliant accounting export." }, "visibility": { "type": "string", "description": "Controls where the values of this custom field are visible.\n`ADMIN_AND_CARDHOLDER` makes the values visible to both admins and cardholders.\n`ADMIN_ONLY` makes the values visible only to admins.\n`NOWHERE` hides the values from both admins and cardholders.\nOptional; defaults to `ADMIN_AND_CARDHOLDER` when omitted.\n", "enum": [ "ADMIN_AND_CARDHOLDER", "ADMIN_ONLY", "NOWHERE" ], "default": "ADMIN_AND_CARDHOLDER" } } } } } }, "responses": { "200": { "description": "Ok. The custom field can be used after you received the callback for the `CUSTOM_FIELD_CREATED` event.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The id of the custom field." }, "label": { "type": "string", "description": "The label of the custom field, displayed in a UI for example." }, "description": { "type": "string", "description": "The description of the custom field, displayed in a UI for example.", "nullable": true }, "defaultValue": { "type": "string", "description": "The default value of the custom field, optional.", "nullable": true }, "type": { "type": "string", "description": "The type of the custom field.\n`TEXT` represents a custom field which can store any text value.\n`SELECT` represents a custom field which can store a fixed set of options.\n", "enum": [ "TEXT", "SELECT" ] }, "status": { "type": "string", "description": "The status of the custom field. Only an active custom field can be used.", "enum": [ "ACTIVE", "INACTIVE" ] }, "automationType": { "type": "string", "description": "The automation type of the custom field. For now only `CARD` is supported. This means, that the [custom fields](/docs/custom-fields-on-transactions) default value will be copied to every transaction made with the card the field is set on.", "enum": [ "CARD" ] }, "mandatoryOnAutomation": { "type": "boolean", "description": "If set to true, this means this custom field is mandatory to be filled with a default value on the level of the automation, here `CARD`." }, "mandatoryForExport": { "type": "boolean", "description": "If set to true, this means this custom field is mandatory to be filled on every transaction which should be exported with the Pliant accounting export." }, "visibility": { "type": "string", "description": "Controls where the values of this custom field are visible.\n`ADMIN_AND_CARDHOLDER` makes the values visible to both admins and cardholders.\n`ADMIN_ONLY` makes the values visible only to admins.\n`NOWHERE` hides the values from both admins and cardholders.\n", "enum": [ "ADMIN_AND_CARDHOLDER", "ADMIN_ONLY", "NOWHERE" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "The date and time the custom field was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "The date and time the custom field was last updated.", "nullable": true } } } } } } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "This API uses oAuth2 with client credentials flow to [obtain the Bearer Token](/docs/authenticated-api-usage).", "bearerFormat": "JWT" } }, "schemas": { "Error": { "type": "object", "properties": { "errorCode": { "type": "string", "description": "The error code" }, "exceptionId": { "type": "string", "format": "uuid", "description": "The id of the exception that was thrown" }, "message": { "type": "string", "description": "The cause of the error or further explanations on the error" } } } }, "responses": { "400": { "description": "Bad Request. The API consumer sent a malformed request which could not be processed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized. The API consumer is not authorized to access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden. The API consumer is not allowed to access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too Many Requests. The API consumer has sent too many requests in a given amount of time. Please check our [API guidelines](/docs/pliant-api-guidelines#api-rate-limits).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Detailed description of the error and breached rate limit." } } } } } }, "500": { "description": "Internal Server Error. The request was not completed due to an internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "security": [ { "bearerAuth": [] } ] } ```