Difference between revisions of "API:CustomFieldOption:Update"

From docs
Jump to: navigation, search
(Created page with " == API » Update Custom Field Option == '''URL:''' <nowiki>https://app.callproof.com/api/custom_field/option/update/</nowiki> '''Method:''' POST '''Required Fields...")
 
 
Line 2: Line 2:
 
== [[API]] &#187; Update Custom Field Option ==
 
== [[API]] &#187; Update Custom Field Option ==
  
−
'''URL:''' <nowiki>https://app.callproof.com/api/custom_field/option/update/</nowiki>
+
=== Base URL ===
 +
https://app.callproof.com
  
−
'''Method:''' POST
+
=== Endpoint ===
 +
/api/custom_field/option/update/
  
−
'''Required Fields:'''
+
=== Purpose ===
 +
Updates an existing selectable option for a custom field in your CallProof company. Use this to change an option’s display name, order, or points value for custom fields that use option-based choices.
  
−
* '''''api_key[key]''''' - API Key
+
=== HTTP Method ===
−
* '''''api_key[secret]''''' - API Key Secret
+
POST
−
* '''''custom_field_option[id]''''' - Custom Field Option ID
 
  
−
'''Optional Fields:'''
+
=== Headers ===
 +
{| class="wikitable"
 +
! Header !! Required !! Description
 +
|-
 +
| Content-Type || Yes || Must be <code>application/json</code>.
 +
|}
  
−
* '''''custom_field_option[name]''''' - Custom Field Option name
+
=== Security ===
−
* '''''custom_field_option[position]''''' - Custom Field Option position (e.g. 1, 2, 3)
+
* '''Yes''' – Requires a valid API key and secret with permission to update custom fields. Credentials are sent in the request body.
−
* '''''custom_field_option[points]''''' - Custom Field Option points for assigning value
 
  
−
'''Data Returned:'''
+
=== Parameters ===
  
−
* '''''results''''' - Custom Field Option
+
==== Path Parameters ====
−
* '''''errors''''' - Array of errors produced by the request
+
None.
−
* '''''code''''' - HTTP request status
+
 
 +
==== Query Parameters ====
 +
None.
 +
 
 +
==== Request Body ====
 +
{| class="wikitable"
 +
! Parameter !! Type !! Required !! Description
 +
|-
 +
| api_key || object || Yes || Authentication credentials object.
 +
|-
 +
| api_key.key || string || Yes || Public API key assigned to your CallProof account.
 +
|-
 +
| api_key.secret || string || Yes || Private API secret paired with the API key.
 +
|-
 +
| custom_field_option || object || Yes || Custom field option update payload.
 +
|-
 +
| custom_field_option.id || integer || Yes || Unique identifier of the custom field option to update. The option must belong to a custom field in your company.
 +
|-
 +
| custom_field_option.name || string || No || Updated option display name. Maximum 64 characters. If omitted, the option name is set to an empty string.
 +
|-
 +
| custom_field_option.position || integer || No || Updated display order position. Applied only when a non-zero integer is provided.
 +
|-
 +
| custom_field_option.points || integer || No || Updated points value. Applied only when a non-zero integer is provided.
 +
|}
 +
 
 +
=== cURL Example ===
 +
<pre>
 +
curl -X POST "https://app.callproof.com/api/custom_field/option/update/" \
 +
  -H "Content-Type: application/json" \
 +
  -d '{
 +
    "api_key": {
 +
      "key": "YOUR_API_KEY",
 +
      "secret": "YOUR_API_SECRET"
 +
    },
 +
    "custom_field_option": {
 +
      "id": 101,
 +
      "name": "Manufacturing",
 +
      "position": 1,
 +
      "points": 0
 +
    }
 +
  }'
 +
</pre>
 +
 
 +
=== Successful Response (200) ===
 +
Indicates the custom field option was updated successfully. The response returns the updated option details.
 +
 
 +
{| class="wikitable"
 +
! Field !! Type !! Description
 +
|-
 +
| results || object || Updated custom field option details.
 +
|-
 +
| results.id || integer || Unique identifier for the option.
 +
|-
 +
| results.name || string || Option display name.
 +
|-
 +
| results.cfield_id || integer || Identifier of the custom field that owns the option.
 +
|-
 +
| results.cfield || string || Name of the custom field that owns the option.
 +
|-
 +
| results.is_default || string || <code>1</code> if this option is a default option; otherwise <code>0</code>.
 +
|-
 +
| results.position || integer || Option display order position.
 +
|-
 +
| results.points || integer || Points value assigned to the option.
 +
|-
 +
| errors || object || Empty object when the request succeeds.
 +
|-
 +
| code || integer || HTTP-style status value; <code>200</code> on success.
 +
|}
 +
 
 +
Example response:
 +
<pre>
 +
{
 +
  "results": {
 +
    "id": 101,
 +
    "name": "Manufacturing",
 +
    "cfield_id": 12,
 +
    "cfield": "Industry",
 +
    "is_default": "1",
 +
    "position": 1,
 +
    "points": 0
 +
  },
 +
  "errors": {},
 +
  "code": 200
 +
}
 +
</pre>
 +
 
 +
=== Notes ===
 +
* This endpoint updates a custom field option, not the parent custom field definition.
 +
* The option must belong to a custom field in your company.
 +
* If <code>name</code> is omitted, the option name is set to an empty string.
 +
* <code>position</code> is updated only when a non-zero integer is supplied.
 +
* <code>points</code> is updated only when a non-zero integer is supplied.
 +
* To update the parent custom field definition, use <code>/api/custom_field/update/</code>.
 +
* To retrieve custom fields and their options, use <code>/api/custom_fields/get/</code>.
 +
 
 +
=== Error Responses ===
 +
{| class="wikitable"
 +
! Status Code !! Meaning
 +
|-
 +
| 400 || Bad Request – The option ID is missing, invalid, or does not belong to a custom field in your company.
 +
|-
 +
| 401 || Unauthorized – The API key and/or secret is missing, invalid, inactive, associated with a disabled account, or lacks permission to update custom fields.
 +
|-
 +
| 405 || Method Not Allowed – A method other than POST was used.
 +
|-
 +
| 500 || Internal Server Error – An unexpected server problem occurred. Not specified in Swagger.
 +
|}
 +
 
 +
'''400 response body example:'''
 +
<pre>
 +
{
 +
  "results": [],
 +
  "errors": ["Invalid 'id' field"],
 +
  "code": 400
 +
}
 +
</pre>
 +
 
 +
'''401 response body example:'''
 +
<pre>
 +
{
 +
  "results": [],
 +
  "errors": ["Invalid API Key"],
 +
  "code": 401
 +
}
 +
</pre>
 +
 
 +
'''405 response body example:'''
 +
<pre>
 +
{
 +
  "results": [],
 +
  "errors": ["Method not allowed"],
 +
  "code": 405
 +
}
 +
</pre>

Latest revision as of 13:53, 17 July 2026

API » Update Custom Field Option

Base URL

https://app.callproof.com

Endpoint

/api/custom_field/option/update/

Purpose

Updates an existing selectable option for a custom field in your CallProof company. Use this to change an option’s display name, order, or points value for custom fields that use option-based choices.

HTTP Method

POST

Headers

Header Required Description
Content-Type Yes Must be application/json.

Security

  • Yes – Requires a valid API key and secret with permission to update custom fields. Credentials are sent in the request body.

Parameters

Path Parameters

None.

Query Parameters

None.

Request Body

Parameter Type Required Description
api_key object Yes Authentication credentials object.
api_key.key string Yes Public API key assigned to your CallProof account.
api_key.secret string Yes Private API secret paired with the API key.
custom_field_option object Yes Custom field option update payload.
custom_field_option.id integer Yes Unique identifier of the custom field option to update. The option must belong to a custom field in your company.
custom_field_option.name string No Updated option display name. Maximum 64 characters. If omitted, the option name is set to an empty string.
custom_field_option.position integer No Updated display order position. Applied only when a non-zero integer is provided.
custom_field_option.points integer No Updated points value. Applied only when a non-zero integer is provided.

cURL Example

curl -X POST "https://app.callproof.com/api/custom_field/option/update/" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": {
      "key": "YOUR_API_KEY",
      "secret": "YOUR_API_SECRET"
    },
    "custom_field_option": {
      "id": 101,
      "name": "Manufacturing",
      "position": 1,
      "points": 0
    }
  }'

Successful Response (200)

Indicates the custom field option was updated successfully. The response returns the updated option details.

Field Type Description
results object Updated custom field option details.
results.id integer Unique identifier for the option.
results.name string Option display name.
results.cfield_id integer Identifier of the custom field that owns the option.
results.cfield string Name of the custom field that owns the option.
results.is_default string 1 if this option is a default option; otherwise 0.
results.position integer Option display order position.
results.points integer Points value assigned to the option.
errors object Empty object when the request succeeds.
code integer HTTP-style status value; 200 on success.

Example response: 

{
  "results": {
    "id": 101,
    "name": "Manufacturing",
    "cfield_id": 12,
    "cfield": "Industry",
    "is_default": "1",
    "position": 1,
    "points": 0
  },
  "errors": {},
  "code": 200
}

Notes

  • This endpoint updates a custom field option, not the parent custom field definition.
  • The option must belong to a custom field in your company.
  • If name is omitted, the option name is set to an empty string.
  • position is updated only when a non-zero integer is supplied.
  • points is updated only when a non-zero integer is supplied.
  • To update the parent custom field definition, use /api/custom_field/update/.
  • To retrieve custom fields and their options, use /api/custom_fields/get/.

Error Responses

Status Code Meaning
400 Bad Request – The option ID is missing, invalid, or does not belong to a custom field in your company.
401 Unauthorized – The API key and/or secret is missing, invalid, inactive, associated with a disabled account, or lacks permission to update custom fields.
405 Method Not Allowed – A method other than POST was used.
500 Internal Server Error – An unexpected server problem occurred. Not specified in Swagger.

400 response body example: 

{
  "results": [],
  "errors": ["Invalid 'id' field"],
  "code": 400
}

401 response body example: 

{
  "results": [],
  "errors": ["Invalid API Key"],
  "code": 401
}

405 response body example: 

{
  "results": [],
  "errors": ["Method not allowed"],
  "code": 405
}
Retrieved from "http://docs.callproof.com/index.php?title=API:CustomFieldOption:Update&oldid=2331"