--- updatedAt: 2026-04-21T09:28:39.000Z agentTools: projectIndex: https://customer-api.getpliant.com/llms.txt --- # Create Custom Field Option Add a new, single [custom field option](/docs/custom-fields-on-transactions) to a given custom field of type `SELECT`. # OpenAPI definition ```json { "openapi": "3.0.1", "info": { "contact": { "name": "API Support", "email": "support@getpliant.com", "url": "https://www.getpliant.com" }, "title": "Pliant Customer API", "description": "Pliant Customer 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": "Card Accounts", "description": "This tag is for operations related to card accounts" }, { "name": "Cards", "description": "This tag is for operations related to cards" }, { "name": "Custom Fields", "description": "This tag is for operations related to custom fields" } ], "paths": { "/card-accounts/{cardAccountId}/deactivate": { "post": { "summary": "Deactivate Card Account", "description": "Deactivates a card account. The organization ownership is automatically determined from the card account. A card account with `status` `SUPERSEDED` cannot be deactivated, since it is already in a terminal state.", "tags": [ "Card Accounts" ], "operationId": "deactivate-card-account", "parameters": [ { "name": "cardAccountId", "in": "path", "required": true, "description": "The unique identifier of the card account to deactivate.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Card account successfully deactivated.", "content": { "application/json": { "schema": { "$ref": "#/paths/~1card-accounts/post/responses/201/content/application~1json/schema" } } } }, "400": { "description": "Bad Request - Cannot deactivate the default card account.", "content": { "application/json": { "schema": { "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" } } } } } }, "401": { "$ref": "#/paths/~1cards/get/responses/401" }, "403": { "$ref": "#/paths/~1cards/get/responses/403" }, "404": { "$ref": "#/paths/~1cards/post/responses/404" }, "429": { "$ref": "#/paths/~1cards/get/responses/429" }, "500": { "$ref": "#/paths/~1cards/get/responses/500" } } } }, "/cards": { "get": { "summary": "List Cards", "description": "Returns a list of cards. You can use the `limit`, `page`, `sortBy` and `sortDirection` parameters to filter and sort the results.\n\n**This endpoint has changed in comparison to the previous version of the API.** The following changes were made:\n- changed the enumeration for the status field in the response body\n", "tags": [ "Cards" ], "operationId": "get-cards", "parameters": [ { "name": "organizationId", "in": "query", "description": "The ID of the organization to filter by.", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "name": "cardAccountId", "in": "query", "description": "The ID of the card account to filter by. A card always carries the card account it is currently assigned to. Once a card has been reassigned (see the `CARD_REASSIGNED` callback), it is only returned for its new card account, not for the superseded one.", "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "description": "A list of statuses of cards to filter by.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "PENDING", "PENDING_ACTIVATION", "PENDING_ISSUANCE", "PENDING_REGISTRATION", "REQUEST_APPROVED", "REQUESTED", "REQUEST_CANCELLED", "REQUEST_REJECTED", "ACTIVE", "LOCKED", "LOCKED_PIN", "EXPIRED", "TERMINATED", "TERMINATED_LOST", "TERMINATED_STOLEN" ] } } }, { "name": "cardholderId", "in": "query", "description": "The ID of the [cardholder](/docs/cardholder-entity) to filter by.", "schema": { "type": "string", "format": "uuid" } }, { "name": "type", "in": "query", "deprecated": true, "description": "**DEPRECATED**: Use `cardConfig` parameter instead. A list of types of cards to filter by.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "VIRTUAL", "SINGLE_USE", "TRAVEL", "PHYSICAL", "BLACK" ] } } }, { "name": "cardConfig", "in": "query", "description": "Filter by exact card configuration (e.g., PLIANT_PHYSICAL, PLIANT_VIRTUAL_TRAVEL, PLIANT_SINGLE_USE). Can be specified multiple times for filtering by multiple configurations.", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "fromDate", "in": "query", "description": "The `from` date to filter by as zero-offset UTC time. The date boundary is inclusive. Meaning we compare with `>=`.", "schema": { "type": "string", "format": "date-time", "example": "2024-07-19T15:00:00.000000Z" } }, { "name": "toDate", "in": "query", "description": "The `to` date to filter by as zero-offset UTC time. The date boundary is inclusive. Meaning we compare with `<=`.", "schema": { "type": "string", "format": "date-time", "example": "2024-07-19T15:00:00.000000Z" } }, { "name": "byDateField", "in": "query", "description": "The date field to filter by if `fromDate` and `toDate` are present.", "schema": { "type": "string", "nullable": true, "enum": [ "createdAt", "updatedAt" ], "default": "createdAt" } }, { "name": "limit", "in": "query", "description": "The maximum number of items to return per page. The default value if not provided is 100, the maximum allowed value is 1000.", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "description": "The page number to return, starting with 0, this counts up to the total number of pages. The total number of pages is determined by the total number of records divided by the limit.", "schema": { "type": "integer" } }, { "name": "sortBy", "in": "query", "description": "The field to sort by.", "schema": { "type": "string", "enum": [ "organizationId", "status", "cardholderId", "updatedAt" ] } }, { "name": "sortDirection", "in": "query", "description": "The direction to sort by.", "schema": { "type": "string", "enum": [ "ASC", "DESC" ] } } ], "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "cardId": { "type": "string", "format": "uuid", "description": "The unique identifier of the card." }, "organizationId": { "type": "string", "format": "uuid", "description": "The unique identifier of the organization." }, "cardAccountId": { "type": "string", "format": "uuid", "description": "The unique identifier of the card account." }, "cardholderId": { "type": "string", "format": "uuid", "description": "The unique identifier of the cardholder." }, "type": { "type": "string", "deprecated": true, "nullable": true, "description": "Deprecated, please use `cardConfig` instead.\n`VIRTUAL` - Virtual credit card\n`SINGLE_USE` - One-time virtual credit card (only one authorization allowed per card)\n`PHYSICAL` - Physical credit card\n`BLACK` - Physical black premium credit card\n`TRAVEL` - Virtual cards used specifically in travel industry related use cases\n", "enum": [ "VIRTUAL", "SINGLE_USE", "PHYSICAL", "BLACK", "TRAVEL" ] }, "cardConfig": { "type": "string", "description": "The Pliant card configuration of this card. This describes all feature of this card in one single configuration, e.g. the type of the card and also the design of the card etc. It replaces the deprecated card `type`. Please refer to the [guide section](/docs/card-entity) to learn more about possible values." }, "platformFee": { "type": "boolean", "description": "Whether the card is used for the internal Pliant platform fee or not." }, "cardDesignId": { "type": "string", "format": "uuid", "description": "The unique identifier of the card design used for this specific card." }, "cardDesignLogoName": { "type": "string", "nullable": true, "description": "The name of the card design used for this specific card." }, "createdAt": { "type": "string", "format": "date-time", "description": "The date-time when card was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "The date-time when card was updated." } } } }, "hasNextPage": { "type": "boolean", "description": "Indicates whether there is a next page available." } } } } } }, "400": { "description": "Bad Request. The API consumer sent a malformed request which could not be processed.", "content": { "application/json": { "schema": { "$ref": "#/paths/~1card-accounts~1{cardAccountId}~1deactivate/post/responses/400/content/application~1json/schema" } } } }, "401": { "description": "Unauthorized. The API consumer is not authorized to access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/paths/~1card-accounts~1{cardAccountId}~1deactivate/post/responses/400/content/application~1json/schema" } } } }, "403": { "description": "Forbidden. The API consumer is not allowed to access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/paths/~1card-accounts~1{cardAccountId}~1deactivate/post/responses/400/content/application~1json/schema" } } } }, "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": "#/paths/~1card-accounts~1{cardAccountId}~1deactivate/post/responses/400/content/application~1json/schema" } } } } } } }, "/transactions/custom-fields/{customFieldId}/options": { "post": { "summary": "Create Custom Field Option", "description": "Add a new, single [custom field option](/docs/custom-fields-on-transactions) to a given custom field of type `SELECT`.", "tags": [ "Custom Fields" ], "operationId": "create-custom-field-option", "parameters": [ { "name": "customFieldId", "required": true, "in": "path", "description": "The unique identifier of the custom field for which you want to add a new option.", "schema": { "type": "string", "format": "uuid" } }, { "name": "organizationId", "required": true, "in": "query", "description": "The unique identifier of the organization to create the custom field option for.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "value", "isDefault" ], "properties": { "name": { "type": "string", "description": "The name of the custom field option, readable for humans." }, "value": { "type": "string", "description": "The value of the custom field option. This is mostly your internal value you want to process." }, "isDefault": { "type": "boolean", "description": "If set to true, this means this custom field option is the default option for the related custom field." } } } } } }, "responses": { "200": { "description": "Ok. The custom field option can be used after you received the callback for the `CUSTOM_FIELD_OPTION_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 option." }, "customFieldId": { "type": "string", "format": "uuid", "description": "The id of the custom field this option belongs to." }, "name": { "type": "string", "description": "The name of the custom field option, readable for humans." }, "value": { "type": "string", "description": "The value of the custom field option. This is mostly your internal value you want to process." }, "status": { "type": "string", "description": "The status of the custom field option. Only an active custom field option can be used.", "enum": [ "ACTIVE", "INACTIVE" ] }, "source": { "type": "string", "description": "The source of the custom field option, i.e. how it was created. `PLIANT` means it was created via the Pliant web app. `API` means it was created via the Pliant API. `ACCOUNTING_SYSTEM` means it was created via the accounting system used by the organization.", "enum": [ "PLIANT", "API", "ACCOUNTING_SYSTEM" ] }, "externalReference": { "type": "string", "description": "The external reference of the custom field option. This is the reference in the accounting system and used only there.", "nullable": true }, "isDefault": { "type": "boolean", "description": "If set to true, this means this custom field option is the default option for the related custom field." }, "createdAt": { "type": "string", "format": "date-time", "description": "The date and time the custom field option was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "The date and time the custom field option was last updated." } } } } } } } } }, "400": { "$ref": "#/paths/~1cards/get/responses/400" }, "401": { "$ref": "#/paths/~1cards/get/responses/401" }, "403": { "$ref": "#/paths/~1cards/get/responses/403" }, "429": { "$ref": "#/paths/~1cards/get/responses/429" }, "500": { "$ref": "#/paths/~1cards/get/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" } } }, "security": [ { "bearerAuth": [] } ] } ```