Difference between revisions of "API:CustomField:Create"

From docs
Jump to: navigation, search
(Created page with " == API » Update Custom Field == '''URL:''' <nowiki>https://app.callproof.com/api/custom_field/update/</nowiki> '''Method:''' POST '''Required Fields:''' * '''''a...")
 
 
(One intermediate revision by one other user not shown)
Line 1: Line 1:
  
−
== [[API]] &#187; Update Custom Field ==
+
== [[API]] &#187; Create Custom Field ==
  
−
'''URL:''' <nowiki>https://app.callproof.com/api/custom_field/update/</nowiki>
+
=== Base URL ===
 +
https://app.callproof.com
  
−
'''Method:''' POST
+
=== Endpoint ===
 +
/api/custom_field/new/
  
−
'''Required Fields:'''
+
=== Purpose ===
 +
Creates a new custom field definition in your CallProof company. Use this to add a field that can later store values on contacts or other supported business areas, including field type, display order, points, default option, and related field links.
  
−
* '''''api_key[key]''''' - API Key
+
=== HTTP Method ===
−
* '''''api_key[secret]''''' - API Key Secret
+
POST
−
* '''''custom_field[name]''''' - Custom Field name
 
−
* '''''custom_field[cfield_table]''''' - Custom Field table (contact, eform)
 
  
−
'''Optional Fields:'''
+
=== Headers ===
 +
{| class="wikitable"
 +
! Header !! Required !! Description
 +
|-
 +
| Content-Type || Yes || Must be <code>application/json</code>.
 +
|}
  
−
* '''''custom_field[cfield_type]''''' - Custom Field extension (text, select, radio, checkbox, textarea, date, time, datetime, integer, decimal, auto_integer, image)
+
=== Security ===
−
* '''''custom_field[cfield_option_default]''''' - Custom Field default option for select and radio cfield_types
+
* '''Yes''' – Requires a valid API key and secret with permission to create custom fields. Credentials are sent in the request body.
−
* '''''custom_field[regular_field]''''' - Custom Field regular field (first_name, last_name, email, address, address2, city, state_id, zip, account, title, website, country_id, contact_type_id, company_name, only applies to Event Forms)
 
−
* '''''custom_field[custom_field]''''' - Custom Field custom field (only applies to Event Forms)
 
−
* '''''custom_field[position]''''' - Custom Field position (e.g. 1, 2, 3)
 
−
* '''''custom_field[points]''''' - Custom Field points for assigning value
 
  
−
'''Data Returned:'''
+
=== Parameters ===
  
−
* '''''results''''' - Custom Field
+
==== 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 || object || Yes || Custom field creation payload.
 +
|-
 +
| custom_field.cfield_table || string || Yes || Business area/table name for the custom field (for example, <code>contact</code>). Must match a recognized table name.
 +
|-
 +
| custom_field.cfield_type || string || Yes || Custom field type name (for example, text or select). Must match a recognized field type.
 +
|-
 +
| custom_field.name || string || No || Custom field display name. Maximum 64 characters. If omitted, an empty name may be stored.
 +
|-
 +
| custom_field.position || integer || No || Display order position. If omitted, the next available position for the selected table is assigned.
 +
|-
 +
| custom_field.points || integer || No || Points value assigned to the field.
 +
|-
 +
| custom_field.cfield_option_default || string || No || Default option name for fields that support options. Applied when a matching option exists.
 +
|-
 +
| custom_field.regular_field || string || No || Related regular field name, when applicable.
 +
|-
 +
| custom_field.custom_field || string || No || Linked/parent custom field name, when applicable.
 +
|}
 +
 
 +
=== cURL Example ===
 +
<pre>
 +
curl -X POST "https://app.callproof.com/api/custom_field/new/" \
 +
  -H "Content-Type: application/json" \
 +
  -d '{
 +
    "api_key": {
 +
      "key": "YOUR_API_KEY",
 +
      "secret": "YOUR_API_SECRET"
 +
    },
 +
    "custom_field": {
 +
      "name": "Industry",
 +
      "cfield_table": "contact",
 +
      "cfield_type": "select",
 +
      "position": 1,
 +
      "points": 0
 +
    }
 +
  }'
 +
</pre>
 +
 
 +
=== Successful Response (200) ===
 +
Indicates the custom field definition was created successfully. The response returns the new field definition.
 +
 
 +
{| class="wikitable"
 +
! Field !! Type !! Description
 +
|-
 +
| results || object || Newly created custom field definition.
 +
|-
 +
| results.id || integer || Unique identifier for the custom field.
 +
|-
 +
| results.name || string || Custom field display name.
 +
|-
 +
| results.cfield_table || string || Business area where the custom field is used.
 +
|-
 +
| results.cfield_type || string || Type of custom field.
 +
|-
 +
| results.cfield_option_default || string || Default option name, or empty if none.
 +
|-
 +
| results.rfield || string || Related regular field name, when applicable.
 +
|-
 +
| results.cfield || string || Linked/parent custom field name, when applicable.
 +
|-
 +
| results.position || integer || Display order position.
 +
|-
 +
| results.points || integer || Points value assigned to the field.
 +
|-
 +
| results.hide_on_checkout || string || <code>1</code> if hidden during checkout; otherwise <code>0</code>.
 +
|-
 +
| results.options || array || Selectable options configured for the custom field. Typically empty immediately after creation.
 +
|-
 +
| errors || object || Empty object when the request succeeds.
 +
|-
 +
| code || integer || HTTP-style status value; <code>200</code> on success.
 +
|}
 +
 
 +
Example response:
 +
<pre>
 +
{
 +
  "results": {
 +
    "id": 12,
 +
    "name": "Industry",
 +
    "cfield_table": "contact",
 +
    "cfield_type": "select",
 +
    "cfield_option_default": "",
 +
    "rfield": "",
 +
    "cfield": "",
 +
    "position": 1,
 +
    "points": 0,
 +
    "hide_on_checkout": "0",
 +
    "options": []
 +
  },
 +
  "errors": {},
 +
  "code": 200
 +
}
 +
</pre>
 +
 
 +
=== Notes ===
 +
* This endpoint creates a custom field definition, not a value on a specific contact.
 +
* <code>cfield_table</code> and <code>cfield_type</code> are required and must match recognized values.
 +
* If <code>position</code> is omitted, the next available position for the selected table is assigned automatically.
 +
* <code>cfield_option_default</code> is applied only when a matching option name already exists.
 +
* Newly created fields typically have an empty options list until options are added separately.
 +
* Field-level validation failures typically return HTTP <code>200</code> with details in the <code>errors</code> object and an empty <code>results</code> object.
 +
* To add or update options for a field, use <code>/api/custom_field/option/new/</code> and <code>/api/custom_field/option/update/</code>.
 +
* To set values on a contact, use <code>/api/contact/custom_fields/update/</code>.
 +
 
 +
=== Error Responses ===
 +
{| class="wikitable"
 +
! Status Code !! Meaning
 +
|-
 +
| 200 || Validation issue – The custom field table and/or type is missing or invalid. Details are provided in the <code>errors</code> object.
 +
|-
 +
| 401 || Unauthorized – The API key and/or secret is missing, invalid, inactive, associated with a disabled account, or lacks permission to create 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.
 +
|}
 +
 
 +
'''200 validation response example:'''
 +
<pre>
 +
{
 +
  "results": {},
 +
  "errors": {
 +
    "cfield_table": "required field",
 +
    "cfield_type": "required field"
 +
  },
 +
  "code": 200
 +
}
 +
</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:54, 17 July 2026

API » Create Custom Field

Base URL

https://app.callproof.com

Endpoint

/api/custom_field/new/

Purpose

Creates a new custom field definition in your CallProof company. Use this to add a field that can later store values on contacts or other supported business areas, including field type, display order, points, default option, and related field links.

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 create 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 object Yes Custom field creation payload.
custom_field.cfield_table string Yes Business area/table name for the custom field (for example, contact). Must match a recognized table name.
custom_field.cfield_type string Yes Custom field type name (for example, text or select). Must match a recognized field type.
custom_field.name string No Custom field display name. Maximum 64 characters. If omitted, an empty name may be stored.
custom_field.position integer No Display order position. If omitted, the next available position for the selected table is assigned.
custom_field.points integer No Points value assigned to the field.
custom_field.cfield_option_default string No Default option name for fields that support options. Applied when a matching option exists.
custom_field.regular_field string No Related regular field name, when applicable.
custom_field.custom_field string No Linked/parent custom field name, when applicable.

cURL Example

curl -X POST "https://app.callproof.com/api/custom_field/new/" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": {
      "key": "YOUR_API_KEY",
      "secret": "YOUR_API_SECRET"
    },
    "custom_field": {
      "name": "Industry",
      "cfield_table": "contact",
      "cfield_type": "select",
      "position": 1,
      "points": 0
    }
  }'

Successful Response (200)

Indicates the custom field definition was created successfully. The response returns the new field definition.

Field Type Description
results object Newly created custom field definition.
results.id integer Unique identifier for the custom field.
results.name string Custom field display name.
results.cfield_table string Business area where the custom field is used.
results.cfield_type string Type of custom field.
results.cfield_option_default string Default option name, or empty if none.
results.rfield string Related regular field name, when applicable.
results.cfield string Linked/parent custom field name, when applicable.
results.position integer Display order position.
results.points integer Points value assigned to the field.
results.hide_on_checkout string 1 if hidden during checkout; otherwise 0.
results.options array Selectable options configured for the custom field. Typically empty immediately after creation.
errors object Empty object when the request succeeds.
code integer HTTP-style status value; 200 on success.

Example response: 

{
  "results": {
    "id": 12,
    "name": "Industry",
    "cfield_table": "contact",
    "cfield_type": "select",
    "cfield_option_default": "",
    "rfield": "",
    "cfield": "",
    "position": 1,
    "points": 0,
    "hide_on_checkout": "0",
    "options": []
  },
  "errors": {},
  "code": 200
}

Notes

  • This endpoint creates a custom field definition, not a value on a specific contact.
  • cfield_table and cfield_type are required and must match recognized values.
  • If position is omitted, the next available position for the selected table is assigned automatically.
  • cfield_option_default is applied only when a matching option name already exists.
  • Newly created fields typically have an empty options list until options are added separately.
  • Field-level validation failures typically return HTTP 200 with details in the errors object and an empty results object.
  • To add or update options for a field, use /api/custom_field/option/new/ and /api/custom_field/option/update/.
  • To set values on a contact, use /api/contact/custom_fields/update/.

Error Responses

Status Code Meaning
200 Validation issue – The custom field table and/or type is missing or invalid. Details are provided in the errors object.
401 Unauthorized – The API key and/or secret is missing, invalid, inactive, associated with a disabled account, or lacks permission to create 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.

200 validation response example: 

{
  "results": {},
  "errors": {
    "cfield_table": "required field",
    "cfield_type": "required field"
  },
  "code": 200
}

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:CustomField:Create&oldid=2333"